Document some crap.

common/content/modules.js

@@ -3,12 +3,60 @@
 // This work is licensed for reuse under an MIT license. Details are
 // given in the LICENSE.txt file included with this file.
 
-const ModuleBase = Class("ModuleBase", { requires: [] });
-function Module(name, inst, clas, moduleInit) {
+/**
+ * @class ModuleBase
+ * The base class for all modules.
+ */
+const ModuleBase = Class("ModuleBase", {
+    /**
+     * @property {[string]} A list of module prerequisites which
+     * must be initialized before this module is loaded.
+     */
+    requires: [],
+
+    toString: function () "[module " + this.constructor.name + "]",
+});
+
+/**
+ * @constructor Module
+ *
+ * Constructs a new ModuleBase class and makes arrangements for its
+ * initialization. Arguments marked as optional must be either
+ * entirely elided, or they must have the exact type specified.
+ * Loading semantics are as follows:
+ *
+ *  - A module is garunteed not to be initialized before any of its
+ *    prerequisites as listed in its {@see ModuleBase#requires} member.
+ *  - A module is considered initialized once its been instantiated,
+ *    it's {@see Class#init} method has been called, and its
+ *    instance has been installed into the top-level {@see modules}
+ *    object.
+ *  - Once the module has been initialized, its module-dependent
+ *    initialization functions will be called as described hereafter.
+ * @param {string} name The module's name as it will appear in the
+ *      top-level {@see modules} object.
+ * @param {ModuleBase} base The base class for this module.
+ *      @optional
+ * @param {Object} prototype The prototype for instances of this
+ *      object. The object itself is copied and not used as a
+ *      prototype directly.
+ * @param {Object} classProperties The class properties for the new
+ *      module constructor.
+ *      @optional
+ * @param {Object} moduleInit The module initialization functions
+ *      for the new module. Each function is called as soon as the
+ *      named module has been initialized, but after the module
+ *      itself. The constructors are garunteed to be called in the
+ *      same order that the dependent modules were initialized.
+ *      @optional
+ *
+ * @returns {function} The constructor for the resulting module.
+ */
+function Module(name, prototype, classProperties, moduleInit) {
     var base = ModuleBase;
-    if (callable(inst))
+    if (callable(prototype))
         base = Array.splice(arguments, 1, 1)[0]
-    const module = Class(name, base, inst, clas);
+    const module = Class(name, base, prototype, classProperties);
     module.INIT = moduleInit || {};
     module.requires = inst.requires || [];
     Module.list.push(module);