Add jsdoc

diff --git a/BuildCache.js b/BuildCache.js
index f29e9bf..eac93b3 100644 (file)
--- a/BuildCache.js
+++ b/BuildCache.js
@@ -26,6 +26,16 @@ let util = require('util')
 
 let fs_stat = util.promisify(fs.stat)
 
+/**
+ * Constructs a cache object. The cache object is intended to store objects of
+ * arbitrary JavaScript type, which are built from on-disk source files of some
+ * kind. The cache tracks the source files of each object, and makes sure the
+ * objects are rebuilt as required if the source files change on disk.
+ *
+ * @constructor
+ * @param {boolean} diag - Should diagnostic messages be printed to the
+ *   console.
+ */
 let BuildCache = function(diag) {
   if (!this instanceof BuildCache)
     throw new Error('BuildCache is a constructor')
@@ -33,10 +43,51 @@ let BuildCache = function(diag) {
   this.diag = diag || false
 }
 
+/**
+ * Abstract method which is expected to build and return an object, given its
+ * key. Called from "get()" when the object does not exist or is out of date.
+ *
+ * If this method throws an exception, the key will be deleted from the cache
+ * and the exception re-thrown to the caller of "get()". If there are multiple
+ * callers to "get()" blocking and waiting for the build, they all receive the
+ * same exception object. So one has to be careful the exception is shareable.
+ *
+ * @method
+ * @param {string} key - Usually the path to the main source file on disk.
+ * @param {object} result - A dictionary to receive information about the built
+ *   object, you can optionally set "result.deps" to a list of dependency files
+ *   whose modification would invalidate the just-built and cached object.
+ */
 BuildCache.prototype.build = async function(key, result) {
   throw new Error('not implemented')
 }
 
+/**
+ * Retrieves the object stored in the cache under "key". If "key" already
+ * exists in the cache, then it will be checked for up-to-dateness. If present
+ * and up-to-date then its object is returned directly. Otherwise the abstract
+ * "build()" method is called to attempt to build the object, and either an
+ * exception is thrown or the built object is stored and returned to the
+ * caller.
+ *
+ * Other callers requsting the same object while the original build progresses
+ * will be blocked, and all will wait for the build to complete. In this time,
+ * no new up-to-date check will be initiated. But as soon as the build is
+ * completed and the cache updated, further up-to-date checks become possible.
+ *
+ * An interesting alternate usage is provided for objects whose contents only
+ * matter if they have been rebuilt since last time. For example, suppose we
+ * want to periodically read a configuration file, and then possibly restart
+ * some long-running process if the configuration has changed. Then it is not
+ * necessary to store the result of configuration parsing in the cache, since
+ * it is only needed momentarily (while we're actually restarting the process).
+ * In such case, pass "once = true" and an "undefined" return means no change.
+ *
+ * @method
+ * @param {string} key - Usually the path to the main source file on disk.
+ * @param {boolean} once - If "true", it means the returned object will only be
+ *   used once. See above for a more comprehensive discussion of this feature.
+ */
 BuildCache.prototype.get = async function(key, once) {
   let result = this.map.get(key)
   if (result === undefined) {
@@ -99,6 +150,15 @@ BuildCache.prototype.get = async function(key, once) {
   return value
 }
 
+/**
+ * Call this periodically to allow the cache to clean itself of stale objects.
+ *
+ * The cache cleaning is not yet implemented, but the dummy "kick()" function
+ * is provided so that you can start to put the cleaning infrastructure in your
+ * code already. The constructor arguments might change later for this feature.
+ *
+ * @method
+ */
 BuildCache.prototype.kick = function() {
   // not yet implemented
 }