Add calling API section to README.md, improve remaining text slightly

diff --git a/README.md b/README.md
index b1bc1e0..7ac7c04 100644 (file)
--- a/README.md
+++ b/README.md
@@ -29,6 +29,25 @@ also provides a dependency resolution service for the compiled template. If the
 compiled template wants to load further templates during initialization or run-
 time, it calls back into `jst_cache`, which recursively loads the dependency.
 
+## Calling API
+
+Suppose one has a `JSTCache` instance named `jc`. It behaves somewhat like an
+ES6 `Map` object, except that it only has the `jc.get()` function, because new
+objects are added to the cache by attempting to `get` them.
+
+The interface for the `JSTCache`-provided instance function `jc.get()` is:
+
+`await jc.get(key)` — retrieves the object stored under `key`, where
+`key` is the on-disk pathname to a JST file. What `jc.get()` returns depends on
+how the template is written, usually it is a function that generates HTML code.
+This function (or other result) is cached for the next `jc.get()` of same key.
+
+Before returning the cached copy, the existence and modification time of the
+JST file on disk is checked to make sure that the cache is up-to-date.
+Otherwise, if the file doesn't exist an `ENOENT` exception is thrown, or if the
+file exists it is re-loaded and re-compiled and re-cached for next time. The
+compilation is via disk and is skipped if an up-to-date disk result is present.
+
 ## Template examples
 
 See the `jst` package for more information about what can be in a template.
@@ -241,10 +260,10 @@ would be ignored, since the page template is expecting output to be in `_out`.
 
 ## File management
 
-The `JSTCache` object a "point and shoot" interface which makes it very easy to
-manage on-disk templates. You just call `JSTCache.get()` stating a pathname to
-a template, normally a `*.jst` file, and the template is parsed, compiled to
-JavaScript, and evaluated, with the evaluation result cached for future reuse.
+The `JSTCache` object offers a simple "point and shoot" interface which makes
+it very easy to manage on-disk templates. You call `await jc.get()` stating a
+pathname to a template, normally a `*.jst` file, and the template is parsed,
+compiled to JavaScript, and evaluated, with the result cached for future reuse.
 
 What the `JSTCache.get()` function returns depends on the template source code.
 Template exports are similar but slightly different to CommonJS module exports,
@@ -320,7 +339,7 @@ All of our NPM packages are MIT licensed, please see LICENSE in the repository.
 
 ## Contributions
 
-The `jst` system is under active development (and is part of a larger project
+The JST system is under active development (and is part of a larger project
 that is also under development) and thus the API is tentative. Please go ahead
 and incorporate the system into your project, or try out our example webserver
 built on the system, subject to the caution that the API could change. Please