Cleanup and add some documention.

common/content/buffer.js

@@ -1028,8 +1028,8 @@ function Buffer() //{{{
          * @default The current document.
          * @param {Node} elem The context element.
          * @default <b>doc</b>
-         * @param {boolean} asIterator Whether to return the results as an XPath
+         * @param {boolean} asIterator Whether to return the results as an
-         *     iterator.
+         *     XPath iterator.
          */
         evaluateXPath: function (expression, doc, elem, asIterator)
         {
@@ -1510,7 +1510,7 @@ function Buffer() //{{{
         /**
          * Displays information about the specified element.
          *
-         * @param {Node} elem
+         * @param {Node} elem The element to query.
          */
         showElementInfo: function (elem)
         {
@@ -1848,7 +1848,8 @@ function Marks() //{{{
          * selected from. If it matches [a-z'"], it's a local mark, and can
          * only be recalled from a buffer with a matching URL.
          *
-         * @param {string} mark
+         * @param {string} mark The mark name.
+         * @param {boolean} silent Whether to output error messages.
          */
         // TODO: add support for frameset pages
         add: function (mark, silent)

common/content/commands.js

@@ -181,7 +181,7 @@ Command.prototype = {
      * @param {string} args The args to be parsed and passed to
      *     {@link #action}.
      * @param {boolean} bang Whether this command was executed with a trailing
-     *     !.
+     *     bang.
      * @deprecated
      * @param {number} count Whether this command was executed with a leading
      *     count.
@@ -224,7 +224,7 @@ Command.prototype = {
     /**
      * Returns whether this command may be invoked via <b>name</b>.
      *
-     * @param {string} name
+     * @param {string} name The candidate name.
      * @returns {boolean}
      */
     hasName: function (name)

common/content/completion.js

@@ -547,6 +547,7 @@ CompletionContext.prototype = {
     /**
      * Gets a key from {@link #cache}, setting it to <b>defVal</b> if it
      * doesn't already exists.
+     *
      * @param {string} key
      * @param defVal
      */

common/content/configbase.js

@@ -37,7 +37,7 @@ const configbase = { //{{{
     get browserModes() [modes.NORMAL],
 
     /**
-     * @property {object} Application specific defaults for option values. The
+     * @property {Object} Application specific defaults for option values. The
      *     property names must be the options' canonical names, and the values
      *     must be strings as entered via :set.
      */
@@ -86,7 +86,7 @@ const configbase = { //{{{
     init: function () {},
 
     /**
-     * @property {object} A map between key names for key events should be ignored,
+     * @property {Object} A map between key names for key events should be ignored,
      *     and a mask of the modes in which they should be ignored.
      */
     ignoreKeys: {}, // XXX: be aware you can't put useful values in here, as "modes.NORMAL" etc. are not defined at this time

common/content/events.js

@@ -479,7 +479,7 @@ function Events() //{{{
         let elem = liberator.focus;
         return ((elem instanceof HTMLInputElement && !/image/.test(elem.type)) ||
                  elem instanceof HTMLTextAreaElement ||
-                 elem instanceof HTMLIsIndexElement)
+                 elem instanceof HTMLIsIndexElement);
     }
 
     function triggerLoadAutocmd(name, doc)
@@ -965,18 +965,21 @@ function Events() //{{{
         },
 
         /**
-         * Converts a user-input string of keys into a canonical representation.
+         * Converts a user-input string of keys into a canonical
+         * representation.
          *
          * <C-A> maps to <C-a>, <C-S-a> maps to <C-S-A>
          * <C- > maps to <C-Space>, <S-a> maps to A
          * << maps to <lt><lt>
          *
-         * <S-@> is preserved, as in vim, to allow untypable key-combinations in macros
+         * <S-@> is preserved, as in vim, to allow untypable key-combinations
+         * in macros.
          *
-         * canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values of x.
+         * canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values
+         * of x.
          *
-         * @param {String} keys  messy form
+         * @param {string} keys Messy form.
-         * @returns {String}  canonical form
+         * @returns {string} Canonical form.
          */
         canonicalKeys: function (keys)
         {
@@ -986,16 +989,18 @@ function Events() //{{{
         /**
          * Converts an event string into an array of pseudo-event objects.
          *
-         * These objects can be used as arguments to events.toString or events.create,
+         * These objects can be used as arguments to events.toString or
-         * though they are unlikely to be much use for other purposes. They have many
+         * events.create, though they are unlikely to be much use for other
-         * of the properties you'd expect to find on a real event, but none of the methods.
+         * purposes. They have many of the properties you'd expect to find on a
+         * real event, but none of the methods.
          *
-         * Also may contain two "special" parameters, .liberatorString and .liberatorShift
+         * Also may contain two "special" parameters, .liberatorString and
-         * these are set for characters that can never by typed, but may appear in mappings,
+         * .liberatorShift these are set for characters that can never by
-         * for example <Nop> is passed as liberatorString, and liberatorShift is set when
+         * typed, but may appear in mappings, for example <Nop> is passed as
-         * a user specifies <S-@> where @ is a non-case-changable, non-space character.
+         * liberatorString, and liberatorShift is set when a user specifies
+         * <S-@> where @ is a non-case-changable, non-space character.
          *
-         * @param {String} keys  The string to parse
+         * @param {string} keys The string to parse.
          * @return {Array[Object]}
          */
         fromString: function (input)
@@ -1082,7 +1087,7 @@ function Events() //{{{
          * @param {Event} event
          * @returns {string}
          */
-        toString: function (event, all)
+        toString: function (event)
         {
             if (!event)
                 return "[object Mappings]";
@@ -1197,6 +1202,7 @@ function Events() //{{{
          * Whether <b>key</b> is a key code defined to accept/execute input on
          * the command line.
          *
+         * @param {string} key The key code to test.
          * @returns {boolean}
          */
         isAcceptKey: function (key) key == "<Return>" || key == "<C-j>" || key == "<C-m>",
@@ -1205,11 +1211,12 @@ function Events() //{{{
          * Whether <b>key</b> is a key code defined to reject/cancel input on
          * the command line.
          *
+         * @param {string} key The key code to test.
          * @returns {boolean}
          */
         isCancelKey: function (key) key == "<Esc>" || key == "<C-[>" || key == "<C-c>",
 
-        /*
+        /**
          * Waits for the current buffer to successfully finish loading. Returns
          * true for a successful page load otherwise false.
          *
@@ -1346,7 +1353,9 @@ function Events() //{{{
             // }
         },
 
-        // global escape handler, is called in ALL modes
+        /**
+         *  The global escape key handler. This is called in ALL modes.
+         */
         onEscape: function ()
         {
             if (modes.passNextKey)
@@ -1665,6 +1674,9 @@ function Events() //{{{
         },
 
         // TODO: move to buffer.js?
+        /**
+         * The liberator document loading progress listener.
+         */
         progressListener: {
             QueryInterface: XPCOMUtils.generateQI([
                 Ci.nsIWebProgressListener,

common/content/hints.js

@@ -217,7 +217,7 @@ function Hints() //{{{
         try
         {
             // Need to add the offset to the area element.
-            // Always try to find the top-left point, as per vimperator default.
+            // Always try to find the top-left point, as per liberator default.
             let shape = elem.getAttribute("shape").toLowerCase();
             let coordstr = elem.getAttribute("coords");
             // Technically it should be only commas, but hey
@@ -352,8 +352,8 @@ function Hints() //{{{
      *
      * By default highlights it green instead of yellow.
      *
-     * @param {Number} newID The hint to make active
+     * @param {number} newID The hint to make active.
-     * @param {Number} oldID The currently active hint
+     * @param {number} oldID The currently active hint.
      */
     function showActiveHint(newID, oldID)
     {
@@ -624,7 +624,7 @@ function Hints() //{{{
          * would match the first letters of words. It will always only match
          * words in order.
          *
-         * @param {String} hintString The string typed by the user.
+         * @param {string} hintString The string typed by the user.
          * @param {boolean} allowWordOverleaping Whether to allow non-contiguous
          *     words to match.
          * @returns {function(String):boolean} A function that will filter only
@@ -893,15 +893,16 @@ function Hints() //{{{
          * Creates a new hint mode.
          *
          * @param {string} mode The letter that identifies this mode.
-         * @param {string} description The description to display to the user
+         * @param {string} prompt The description to display to the user
          *     about this mode.
-         * @param {function(Node)} callback The function to be called with the
+         * @param {function(Node)} action The function to be called with the
          *     element that matches.
-         * @param {function():string} selector The function that returns an
+         * @param {function():string} tags The function that returns an
-         *     XPath selector to decide which elements can be hinted (the
+         *     XPath expression to decide which elements can be hinted (the
          *     default returns options.hinttags).
+         * @optional
          */
-        addMode: function (mode)
+        addMode: function (mode, prompt, action, tags)
         {
             hintModes[mode] = Mode.apply(Mode, Array.slice(arguments, 1));
         },

common/content/io.js

@@ -65,7 +65,7 @@ function IO() //{{{
     /////////////////////////////////////////////////////////////////////////////{{{
 
     const WINDOWS = liberator.has("Win32");
-    const EXTENSION_NAME = config.name.toLowerCase(); // "vimperator" or "muttator"
+    const EXTENSION_NAME = config.name.toLowerCase();
 
     const downloadManager = Cc["@mozilla.org/download-manager;1"].createInstance(Ci.nsIDownloadManager);
 
@@ -569,7 +569,7 @@ function IO() //{{{
         expandPath: IO.expandPath,
 
         // TODO: there seems to be no way, short of a new component, to change
-        // the process's CWD - see // https://bugzilla.mozilla.org/show_bug.cgi?id=280953
+        // the process's CWD - see https://bugzilla.mozilla.org/show_bug.cgi?id=280953
         /**
          * Returns the current working directory.
          *
@@ -1119,7 +1119,7 @@ lookup:
         },
 
         // TODO: when https://bugzilla.mozilla.org/show_bug.cgi?id=68702 is
-        // fixed is fixed, should use that instead of a tmpfile
+        // fixed use that instead of a tmpfile
         /**
          * Runs <b>command</b> in a subshell and returns the output in a
          * string. The shell used is that specified by the 'shell' option.

common/content/liberator.js

@@ -26,7 +26,6 @@ the provisions above, a recipient may use your version of this file under
 the terms of any one of the MPL, the GPL or the LGPL.
 }}} ***** END LICENSE BLOCK *****/
 
-
 /** @scope modules */
 
 Cu.import("resource://gre/modules/XPCOMUtils.jsm", modules);
@@ -87,8 +86,8 @@ const liberator = (function () //{{{
         }
     }
 
-    // initially hide all GUI, it is later restored unless the user has :set go= or something
+    // initially hide all GUI elements, they are later restored unless the user
-    // similar in his config
+    // has :set go= or something similar in his config
     function hideGUI()
     {
         let guioptions = config.guioptions;
@@ -108,7 +107,6 @@ const liberator = (function () //{{{
     function getPlatformFeature()
     {
         let platform = navigator.platform;
-
         return /^Mac/.test(platform) ? "MacUnix" : platform == "Win32" ? "Win32" : "Unix";
     }
 
@@ -153,7 +151,7 @@ const liberator = (function () //{{{
     ////////////////////// OPTIONS /////////////////////////////////////////////////
     /////////////////////////////////////////////////////////////////////////////{{{
 
-    // Only general options are added here, which are valid for all Vimperator like extensions
+    // Only general options are added here, which are valid for all Liberator extensions
     registerObserver("load_options", function () {
 
         options.add(["errorbells", "eb"],
@@ -644,7 +642,10 @@ const liberator = (function () //{{{
 
         modules: modules,
 
-        /** @property {number} The current main mode. */
+        /**
+         * @property {number} The current main mode.
+         * @see modes#mainModes
+         */
         get mode()      modes.main,
         set mode(value) modes.main = value,
 
@@ -661,14 +662,13 @@ const liberator = (function () //{{{
 
         forceNewTab: false,
 
-        // these VERSION and DATE tokens are replaced by the Makefile
+        /** @property {string} The Liberator version string. */
-        /** @property {string} The liberator application version string. */
+        version: "###VERSION### (created: ###DATE###)", // these VERSION and DATE tokens are replaced by the Makefile
-        version: "###VERSION### (created: ###DATE###)",
 
         // NOTE: services.get("profile").selectedProfile.name doesn't return
         // what you might expect. It returns the last _actively_ selected
-        // profile (i.e. via the Profile Manager or -p option) rather than the
+        // profile (i.e. via the Profile Manager or -P option) rather than the
-        // current one. These will differ if the current process was run
+        // current profile. These will differ if the current process was run
         // without explicitly selecting a profile.
         /** @property {string} The name of the current user profile. */
         profileName: services.get("directory").get("ProfD", Ci.nsIFile).leafName.replace(/^.+?\./, ""),
@@ -688,7 +688,7 @@ const liberator = (function () //{{{
             rcFile: null,
             /** @property An Ex command to run before any initialization is performed. */
             preCommand: null,
-            /** @property An Ex command to run after all initialization is performed. */
+            /** @property An Ex command to run after all initialization has been performed. */
             postCommand: null
         },
 
@@ -758,15 +758,39 @@ const liberator = (function () //{{{
             return false; // so you can do: if (...) return liberator.beep();
         },
 
+        /**
+         * Creates a new thread.
+         */
         newThread: function () services.get("threadManager").newThread(0),
 
+        /**
+         * Calls a function asynchronously on a new thread.
+         *
+         * @param {nsIThread} thread The thread to call the function on. If no
+         *     thread is specified a new one is created.
+         * @optional
+         * @param {Object} self The 'this' object used when executing the
+         *     function.
+         * @param {function} func The function to execute.
+         *
+         */
         callAsync: function (thread, self, func)
         {
             thread = thread || services.get("threadManager").newThread(0);
             thread.dispatch(new Runnable(self, func, Array.slice(arguments, 3)), thread.DISPATCH_NORMAL);
         },
 
-        // be sure to call GUI related methods like alert() or dump() ONLY in the main thread
+        /**
+         * Calls a function synchronously on a new thread.
+         *
+         * NOTE: Be sure to call GUI related methods like alert() or dump()
+         * ONLY in the main thread.
+         *
+         * @param {nsIThread} thread The thread to call the function on. If no
+         *     thread is specified a new one is created.
+         * @optional
+         * @param {function} func The function to execute.
+         */
         callFunctionInThread: function (thread, func)
         {
             thread = thread || services.get("threadManager").newThread(0);
@@ -775,11 +799,13 @@ const liberator = (function () //{{{
             thread.dispatch(new Runnable(null, func, Array.slice(arguments, 2)), thread.DISPATCH_SYNC);
         },
 
-        // NOTE: "browser.dom.window.dump.enabled" preference needs to be set
         /**
          * Prints a message to the console. If <b>msg</b> is an object it is
          * pretty printed.
          *
+         * NOTE: the "browser.dom.window.dump.enabled" preference needs to be
+         * set.
+         *
          * @param {string|Object} msg The message to print.
          */
         dump: function (msg)
@@ -805,12 +831,26 @@ const liberator = (function () //{{{
             liberator.dump((msg || "Stack") + "\n" + stack);
         },
 
+        /**
+         * Outputs a plain message to the command line.
+         *
+         * @param {string} str The message to output.
+         * @param {number} flags These control the multiline message behaviour.
+         *     See {@link CommandLine#echo}.
+         */
         echo: function (str, flags)
         {
             commandline.echo(str, commandline.HL_NORMAL, flags);
         },
 
         // TODO: Vim replaces unprintable characters in echoerr/echomsg
+        /**
+         * Outputs an error message to the command line.
+         *
+         * @param {string} str The message to output.
+         * @param {number} flags These control the multiline message behaviour.
+         *     See {@link CommandLine#echo}.
+         */
         echoerr: function (str, flags)
         {
             flags |= commandline.APPEND_TO_MESSAGES;
@@ -827,6 +867,16 @@ const liberator = (function () //{{{
         },
 
         // TODO: add proper level constants
+        /**
+         * Outputs an information message to the command line.
+         *
+         * @param {string} str The message to output.
+         * @param {number} verbosity The messages log level (0 - 15). Only
+         *     messages with verbosity less than or equal to the value of the
+         *     'verbosity' option will be output.
+         * @param {number} flags These control the multiline message behaviour.
+         *     See {@link CommandLine#echo}.
+         */
         echomsg: function (str, verbosity, flags)
         {
             // TODO: is there a reason for this? --djk
@@ -851,6 +901,15 @@ const liberator = (function () //{{{
                 commandline.echo(str, commandline.HL_INFOMSG, flags);
         },
 
+        /**
+         * Loads and executes the script referenced by <b>uri</b> in the scope
+         * of the <b>context</b> object.
+         *
+         * @param {string} uri The URI of the script to load. Should be a local
+         *     chrome:, file:, or resource: URL.
+         * @param {Object} context The context object into which the script
+         *     should be loaded.
+         */
         loadScript: function (uri, context)
         {
             services.get("subscriptLoader").loadSubScript(uri, context);
@@ -978,7 +1037,7 @@ const liberator = (function () //{{{
         },
 
         /**
-         * Focus the content window.
+         * Focuses the content window.
          *
          * @param {boolean} clearFocusedElement Remove focus from any focused
          *     element.
@@ -1014,16 +1073,33 @@ const liberator = (function () //{{{
                 elem.focus();
         },
 
-        // does this liberator extension have a certain feature?
+        /**
+         * Returns whether this Liberator extension supports <b>feature</b>.
+         *
+         * @param {string} feature The feature name.
+         * @returns {boolean}
+         */
         has: function (feature) config.features.indexOf(feature) >= 0,
 
+        /**
+         * Returns whether the host application has the specified extension
+         * installed.
+         *
+         * @param {string} name The extension name.
+         * @returns {boolean}
+         */
         hasExtension: function (name)
         {
             let extensions = services.get("extensionManager").getItemList(Ci.nsIUpdateItem.TYPE_EXTENSION, {});
-
             return extensions.some(function (e) e.name == name);
         },
 
+        /**
+         * Returns the URL of the specified help <b>topic</b> if it exists.
+         *
+         * @param {string} topic The help topic to lookup.
+         * @returns {string}
+         */
         findHelp: function (topic)
         {
             let items = completion.runCompleter("help", topic);
@@ -1041,9 +1117,17 @@ const liberator = (function () //{{{
 
             if (partialMatch)
                 return format(partialMatch);
-            return null;
+            else
+                return null;
         },
 
+        /**
+         * Opens the help page containing the specified <b>topic</b> if it
+         * exists.
+         *
+         * @param {string} topic The help topic to open.
+         * @returns {string}
+         */
         help: function (topic)
         {
             let where = (options["newtab"] && options.get("newtab").has("all", "help"))
@@ -1069,6 +1153,11 @@ const liberator = (function () //{{{
                 content.postMessage("fragmentChange", "*");
         },
 
+        /**
+         * The map of global variables.
+         *
+         * These are set and accessed with the "g:" prefix.
+         */
         globalVariables: {},
 
         loadModule: function (name, func) { loadModule(name, func); },
@@ -1239,7 +1328,14 @@ const liberator = (function () //{{{
         // v.plugins.onEvent = <func> function triggered, on keypresses (unless <esc>) (see events.js)
         plugins: plugins,
 
-        // quit liberator, no matter how many tabs/windows are open
+        /**
+         * Quit the host application, no matter how many tabs/windows are open.
+         *
+         * @param {boolean} saveSession If true the current session will be
+         *     saved and restored when the host application is restarted.
+         * @param {boolean} force Forcibly quit irrespective of whether all
+         *    windows could be closed individually.
+         */
         quit: function (saveSession, force)
         {
             // TODO: Use safeSetPref?
@@ -1254,10 +1350,17 @@ const liberator = (function () //{{{
                 window.goQuitApplication();
         },
 
+        /**
+         * Reports an error to both the console and the host application's
+         * Error Console.
+         *
+         * @param {Object} error The error object.
+         */
         reportError: function (error)
         {
             if (Cu.reportError)
                 Cu.reportError(error);
+
             try
             {
                 let obj = {
@@ -1276,7 +1379,7 @@ const liberator = (function () //{{{
         },
 
         /**
-         * Restart the Liberator host application.
+         * Restart the host application.
          */
         restart: function ()
         {
@@ -1302,7 +1405,16 @@ const liberator = (function () //{{{
             services.get("appStartup").quit(Ci.nsIAppStartup.eRestart | Ci.nsIAppStartup.eAttemptQuit);
         },
 
-        parseCommandLine: function (commandline)
+        /**
+         * Parses a Liberator command-line string i.e. the value of the
+         * -liberator command-line option.
+         *
+         * @param {string} cmdline The string to parse for command-line
+         *     options.
+         * @returns {Object}
+         * @see Commands#parseArgs
+         */
+        parseCommandLine: function (cmdline)
         {
             const options = [
                 [["+u"], commands.OPTIONS_STRING],
@@ -1310,10 +1422,9 @@ const liberator = (function () //{{{
                 [["++cmd"], commands.OPTIONS_STRING],
                 [["+c"], commands.OPTIONS_STRING]
             ];
-            return commands.parseArgs(commandline, options, "*");
+            return commands.parseArgs(cmdline, options, "*");
         },
 
-        // TODO: move to {muttator,vimperator,...}.js
         // this function is called when the chrome is ready
         startup: function ()
         {

common/content/style.js

@@ -200,7 +200,7 @@ function Highlights(name, store)
     this.selector = function (class)
     {
         let [, hl, rest] = class.match(/^(\w*)(.*)/);
-        return "[liberator|highlight~=" + hl + "]" + rest
+        return "[liberator|highlight~=" + hl + "]" + rest;
     };
 
     /**

common/content/ui.js

@@ -812,7 +812,6 @@ function CommandLine() //{{{
              validator: Option.validateCompleter
          });
 
-    // TODO: these belong in ui.js
     options.add(["complete", "cpt"],
         "Items which are completed at the :[tab]open prompt",
         "charlist", "slf",
@@ -1072,7 +1071,7 @@ function CommandLine() //{{{
          * Open the command line. The main mode is set to
          * COMMAND_LINE, the extended mode to <b>extendedMode</b>.
          * Further, callbacks defined for <b>extendedMode</b> are
-         * triggered as appropriate (see {@link Liberator#registerCallback}).
+         * triggered as appropriate (see {@link liberator#registerCallback}).
          *
          * @param {string} prompt
          * @param {string} cmd

common/content/util.js

@@ -179,9 +179,9 @@ const util = { //{{{
     },
 
     /**
-     * Split a string on literal occurances of a marker.
+     * Split a string on literal occurrences of a marker.
      *
-     * Specifically this ignores occurences preceded by a backslash, or
+     * Specifically this ignores occurrences preceded by a backslash, or
      * contained within 'single' or "double" quotes.
      *
      * It assumes backslash escaping on strings, and will thus not count quotes
@@ -703,6 +703,7 @@ const util = { //{{{
     }
 }; //}}}
 
+// TODO: Why don't we just push all util.BuiltinType up into modules? --djk
 /**
  * Array utility methods.
  */

muttator/content/config.js

@@ -30,6 +30,7 @@ const config = { //{{{
     /*** required options, no checks done if they really exist, so be careful ***/
     name: "Muttator",
     hostApplication: "Thunderbird", // TODO: can this be found out otherwise? gBrandBundle.getString("brandShortName");
+                                    // Yes, but it will be localized unlike all other strings. So, it's best left until we i18n liberator. --djk
     get mainWindowID() this.isComposeWindow ? "msgcomposeWindow" : "messengerWindow",
 
     /*** optional options, there are checked for existence and a fallback provided  ***/

vimperator/TODO

@@ -6,6 +6,7 @@ ARCHITECTURE:
 	- I made a quick attempt at parameterizing it using attributes but it
 	  breaks Asciidoc formatting in certain unpredictable (to me at least)
 	  contexts. *sigh* --djk
+- decide on how to document Arrays in our jsdoc(ish) documentation.
 
 BUGS:
 - add window resize support to hints

vimperator/content/config.js

@@ -383,7 +383,6 @@ const config = { //{{{
             },
             { argCount: "0" });
 
-        // TODO: move sidebar commands to ui.js?
         commands.add(["sbcl[ose]"],
             "Close the sidebar window",
             function ()