Add some source documentation for AutoCommands.

Also normalise the use of /* */ and // comments.

common/content/buffer.js

@@ -42,7 +42,7 @@ function Buffer() //{{{
     ////////////////////// PRIVATE SECTION /////////////////////////////////////////
     /////////////////////////////////////////////////////////////////////////////{{{
 
-    /* FIXME: This doesn't belong here. */
+    // FIXME: This doesn't belong here.
     let mainWindowID = config.mainWindowID || "main-window";
     let fontSize = util.computedStyle(document.getElementById(mainWindowID)).fontSize;
 

common/content/commands.js

@@ -28,14 +28,14 @@ the terms of any one of the MPL, the GPL or the LGPL.
 
 /** @scope modules */
 
+// Do NOT create instances of this class yourself, use the helper method
+// commands.add() instead
 /**
  * A class representing Ex commands. Instances are created by
  * the {@link Commands} class.
  *
  * @private
  */
-// Do NOT create instances of this class yourself, use the helper method
-// commands.add() instead
 function Command(specs, description, action, extraInfo) //{{{
 {
     if (!specs || !action)
@@ -112,7 +112,7 @@ function Command(specs, description, action, extraInfo) //{{{
      * arguments begin. For instance, with a value of 2, all arguments
      * starting with the third are parsed as a single string, with all
      * quoting characters passed literally. This is especially useful for
-     * commands which take key mappings or ex command lines as
+     * commands which take key mappings or Ex command lines as
      * arguments.
      */
     this.literal     = extraInfo.literal == null ? null : extraInfo.literal;
@@ -133,7 +133,7 @@ function Command(specs, description, action, extraInfo) //{{{
     this.isUserCommand   = extraInfo.isUserCommand || false;
     /**
      * @property {string} For commands defined via :command, contains
-     * the EX command line to be executed upon invocation.
+     * the Ex command line to be executed upon invocation.
      */
     this.replacementText = extraInfo.replacementText || null;
 };

common/content/completion.js

@@ -683,10 +683,10 @@ function Completion() //{{{
         const OFFSET = 0, CHAR = 1, STATEMENTS = 2, DOTS = 3, FULL_STATEMENTS = 4, COMMA = 5, FUNCTIONS = 6;
         let stack = [];
         let functions = [];
-        let top = [];  /* The element on the top of the stack. */
+        let top = [];  // The element on the top of the stack.
-        let last = ""; /* The last opening char pushed onto the stack. */
+        let last = ""; // The last opening char pushed onto the stack.
-        let lastNonwhite = ""; /* Last non-whitespace character we saw. */
+        let lastNonwhite = ""; // Last non-whitespace character we saw.
-        let lastChar = "";     /* Last character we saw, used for \ escaping quotes. */
+        let lastChar = "";     // Last character we saw, used for \ escaping quotes.
         let compl = [];
         let str = "";
 
@@ -733,11 +733,10 @@ function Completion() //{{{
             return iterator;
         }
 
-        /* Search the object for strings starting with @key.
+        // Search the object for strings starting with @key.
-         * If @last is defined, key is a quoted string, it's
+        // If @last is defined, key is a quoted string, it's
-         * wrapped in @last after @offset characters are sliced
+        // wrapped in @last after @offset characters are sliced
-         * off of it and it's quoted.
+        // off of it and it's quoted.
-         */
         this.objectKeys = function objectKeys(obj)
         {
             // Things we can dereference
@@ -809,11 +808,10 @@ function Completion() //{{{
             }
         }
 
-        /* Get an element from the stack. If @n is negative,
+        // Get an element from the stack. If @n is negative,
-         * count from the top of the stack, otherwise, the bottom.
+        // count from the top of the stack, otherwise, the bottom.
-         * If @m is provided, return the @mth value of element @o
+        // If @m is provided, return the @mth value of element @o
-         * of the stack entey at @n.
+        // of the stack entey at @n.
-         */
         let get = function get(n, m, o)
         {
             let a = stack[n >= 0 ? n : stack.length + n];
@@ -827,7 +825,7 @@ function Completion() //{{{
         function buildStack(filter)
         {
             let self = this;
-            /* Push and pop the stack, maintaining references to 'top' and 'last'. */
+            // Push and pop the stack, maintaining references to 'top' and 'last'.
             let push = function push(arg)
             {
                 top = [i, arg, [i], [], [], [], []];
@@ -855,7 +853,7 @@ function Completion() //{{{
                 return ret;
             }
 
-            let i = 0, c = "";     /* Current index and character, respectively. */
+            let i = 0, c = "";     // Current index and character, respectively.
 
             // Reuse the old stack.
             if (str && filter.substr(0, str.length) == str)
@@ -871,11 +869,10 @@ function Completion() //{{{
                 push("#root");
             }
 
-            /* Build a parse stack, discarding entries as opening characters
+            // Build a parse stack, discarding entries as opening characters
-             * match closing characters. The stack is walked from the top entry
+            // match closing characters. The stack is walked from the top entry
-             * and down as many levels as it takes us to figure out what it is
+            // and down as many levels as it takes us to figure out what it is
-             * that we're completing.
+            // that we're completing.
-             */
             str = filter;
             let length = str.length;
             for (; i < length; lastChar = c, i++)
@@ -907,7 +904,7 @@ function Completion() //{{{
                     switch (c)
                     {
                         case "(":
-                            /* Function call, or if/while/for/... */
+                            // Function call, or if/while/for/...
                             if (/[\w$]/.test(lastNonwhite))
                             {
                                 functions.push(i);
@@ -928,7 +925,7 @@ function Completion() //{{{
                             break;
                         case ")": pop("("); break;
                         case "]": pop("["); break;
-                        case "}": pop("{"); /* Fallthrough */
+                        case "}": pop("{"); // Fallthrough
                         case ";":
                             top[FULL_STATEMENTS].push(i);
                             break;
@@ -973,7 +970,7 @@ function Completion() //{{{
             this.context.getCache("eval", Object);
             this.context.getCache("evalContext", function () ({ __proto__: userContext }));
 
-            /* Okay, have parse stack. Figure out what we're completing. */
+            // Okay, have parse stack. Figure out what we're completing.
 
             // Find any complete statements that we can eval before we eval our object.
             // This allows for things like: let doc = window.content.document; let elem = doc.createElement...; elem.<Tab>
@@ -1040,7 +1037,7 @@ function Completion() //{{{
                 cacheKey = null;
                 let obj = [[cache.evalContext, "Local Variables"], [userContext, "Global Variables"],
                            [modules, "modules"], [window, "window"]]; // Default objects;
-                /* Is this an object dereference? */
+                // Is this an object dereference?
                 if (dot < statement) // No.
                     dot = statement - 1;
                 else // Yes. Set the object to the string before the dot.
@@ -1113,11 +1110,11 @@ function Completion() //{{{
             // Otherwise, do nothing.
             if (last == "'" || last == '"')
             {
-                /*
+                //
-                 * str = "foo[bar + 'baz"
+                // str = "foo[bar + 'baz"
-                 * obj = "foo"
+                // obj = "foo"
-                 * key = "bar + ''"
+                // key = "bar + ''"
-                 */
+                //
 
                 // The top of the stack is the sting we're completing.
                 // Wrap it in its delimiters and eval it to process escape sequences.
@@ -1134,14 +1131,13 @@ function Completion() //{{{
                     return this.eval(key);
                 }
 
-                /* Is this an object accessor? */
+                // Is this an object accessor?
                 if (get(-2)[CHAR] == "[") // Are we inside of []?
                 {
-                    /* Stack:
+                    // Stack:
-                     *  [-1]: "...
+                    //  [-1]: "...
-                     *  [-2]: [...
+                    //  [-2]: [...
-                     *  [-3]: base statement
+                    //  [-3]: base statement
-                     */
 
                     // Yes. If the [ starts at the beginning of a logical
                     // statement, we're in an array literal, and we're done.
@@ -1157,11 +1153,10 @@ function Completion() //{{{
                 // Is this a function call?
                 if (get(-2)[CHAR] == "(")
                 {
-                    /* Stack:
+                    // Stack:
-                     *  [-1]: "...
+                    //  [-1]: "...
-                     *  [-2]: (...
+                    //  [-2]: (...
-                     *  [-3]: base statement
+                    //  [-3]: base statement
-                     */
 
                     // Does the opening "(" mark a function call?
                     if (get(-3, 0, FUNCTIONS) != get(-2)[OFFSET])
@@ -1210,15 +1205,15 @@ function Completion() //{{{
                 return;
             }
 
-            /*
+            //
-             * str = "foo.bar.baz"
+            // str = "foo.bar.baz"
-             * obj = "foo.bar"
+            // obj = "foo.bar"
-             * key = "baz"
+            // key = "baz"
-             *
+            //
-             * str = "foo"
+            // str = "foo"
-             * obj = [modules, window]
+            // obj = [modules, window]
-             * key = "foo"
+            // key = "foo"
-             */
+            //
 
             let [offset, obj, key] = getObjKey(-1);
 
@@ -1231,7 +1226,7 @@ function Completion() //{{{
             }
 
             if (!/^(?:[a-zA-Z_$][\w$]*)?$/.test(key))
-                return; /* Not a word. Forget it. Can this even happen? */
+                return; // Not a word. Forget it. Can this even happen?
 
             try
             { // FIXME

common/content/editor.js

@@ -217,7 +217,7 @@ function Editor() //{{{
 
     var myModes = [modes.INSERT, modes.COMMAND_LINE];
 
-    /*             KEYS                          COUNT  CARET                   TEXTAREA            VISUAL_TEXTAREA */
+    //             KEYS                          COUNT  CARET                   TEXTAREA            VISUAL_TEXTAREA
     addMovementMap(["k", "<Up>"],                true,  "lineMove", false,      "cmd_linePrevious", selectPreviousLine);
     addMovementMap(["j", "<Down>", "<Return>"],  true,  "lineMove", true,       "cmd_lineNext",     selectNextLine);
     addMovementMap(["h", "<Left>", "<BS>"],      true,  "characterMove", false, "cmd_charPrevious", "cmd_selectCharPrevious");

common/content/events.js

@@ -182,6 +182,16 @@ function AutoCommands() //{{{
 
         __iterator__: function () util.Array.iterator(store),
 
+        /**
+         * Adds a new autocommand. <b>cmd</b> will be executed when one of the
+         * specified <b>events</b> occurs and the URL of the applicable buffer
+         * matches <b>regex</b>.
+         *
+         * @param {Array} events The array of event names for which this
+         *     autocommand should be executed.
+         * @param {string} regex The URL pattern to match against the buffer URL
+         * @param {string} cmd The Ex command to run
+         */
         add: function (events, regex, cmd)
         {
             if (typeof events == "string")
@@ -194,16 +204,38 @@ function AutoCommands() //{{{
             });
         },
 
+        /**
+         * Returns all autocommands with a matching <b>event</b> and
+         * <b>regex</b>.
+         *
+         * @param {string} event The event name filter.
+         * @param {string} regex The URL pattern filter.
+         * @returns {AutoCommand[]}
+         */
         get: function (event, regex)
         {
             return store.filter(function (autoCmd) matchAutoCmd(autoCmd, event, regex));
         },
 
+        /**
+         * Deletes all autocommands with a matching <b>event</b> and
+         * <b>regex</b>.
+         *
+         * @param {string} event The event name filter.
+         * @param {string} regex The URL pattern filter.
+         */
         remove: function (event, regex)
         {
             store = store.filter(function (autoCmd) !matchAutoCmd(autoCmd, event, regex));
         },
 
+        /**
+         * Lists all autocommands with a matching <b>event</b> and
+         * <b>regex</b>.
+         *
+         * @param {string} event The event name filter.
+         * @param {string} regex The URL pattern filter.
+         */
         list: function (event, regex)
         {
             let cmds = {};
@@ -239,6 +271,14 @@ function AutoCommands() //{{{
             commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
         },
 
+        /**
+         * Triggers the execution of all autocommands registered for
+         * <b>event</b>. A map of <b>args</b> is passed to each autocommand
+         * when it is being executed.
+         *
+         * @param {string} event The event to fire.
+         * @param {Object} args The args to pass to each autocommand.
+         */
         trigger: function (event, args)
         {
             if (options.get("eventignore").has("all", event))
@@ -835,12 +875,18 @@ function Events() //{{{
             }
         },
 
-        // This method pushes keys into the event queue from liberator
+        /**
-        // it is similar to Vim's feedkeys() method, but cannot cope with
+         * Pushes keys into the event queue from liberator it is similar to
-        // 2 partially-fed strings, you have to feed one parsable string
+         * Vim's feedkeys() method, but cannot cope with 2 partially-fed
-        //
+         * strings, you have to feed one parsable string.
-        // @param keys: a string like "2<C-f>" to pass
+         * 
-        //              if you want < to be taken literally, prepend it with a \\
+         * @param {string} keys A string like "2<C-f>" to pass if you want "<"
+         *     to be taken literally, prepend it with a "\\".
+         * @param {boolean} noremap Allow recursive mappings.
+         * @param {boolean} silent Whether the command should be echoed to the
+         *     command-line.
+         * @returns {boolean}
+         */
         feedkeys: function (keys, noremap, silent)
         {
             let doc = window.document;

common/content/find.js

@@ -469,7 +469,6 @@ function Search() //{{{
             // highlighted
             getBrowser().fastFind.collapseSelection();
         }
-
     };
     //}}}
 }; //}}}

common/content/liberator.js

@@ -1057,16 +1057,21 @@ const liberator = (function () //{{{
             consoleService.logStringMessage(config.name.toLowerCase() + ": " + msg);
         },
 
-        // open one or more URLs
+        /**
-        //
+         * Opens one or more URLs. Returns true when load was initiated, or
-        // @param urls: either a string or an array of urls
+         * false on error.
-        //              The array can look like this:
+         *
-        //              ["url1", "url2", "url3", ...] or:
+         * @param {FIXME} urls Either a URL string or an array of URLs.
-        //              [["url1", postdata1], ["url2", postdata2], ...]
+         *     The array can look like this:
-        // @param where: if ommited, CURRENT_TAB is assumed
+         *       ["url1", "url2", "url3", ...]
-        //                  but NEW_TAB is set when liberator.forceNewTab is true.
+         *     or:
-        // @param force: Don't prompt whether to open more than 20 tabs.
+         *       [["url1", postdata1], ["url2", postdata2], ...]
-        // @returns true when load was initiated, or false on error
+         * @param {number} where If ommited, CURRENT_TAB is assumed but NEW_TAB
+         *     is set when liberator.forceNewTab is true.
+         * @param {boolean} force Don't prompt whether to open more than 20
+         *     tabs.
+         * @returns {boolean}
+         */
         open: function (urls, where, force)
         {
             // convert the string to an array of converted URLs

common/content/options.js

@@ -867,7 +867,7 @@ function Options() //{{{
                         isDefault: opt.value == opt.defaultValue,
                         name:      opt.name,
                         default:   opt.defaultValue,
-                        pre:       "\u00a0\u00a0", /* Unicode nonbreaking space. */
+                        pre:       "\u00a0\u00a0", // Unicode nonbreaking space.
                         value:     <></>
                     };
 
@@ -915,7 +915,7 @@ function Options() //{{{
                         default:   loadPreference(pref, null, true),
                         value:     <>={template.highlight(value, true, 100)}</>,
                         name:      pref,
-                        pre:       "\u00a0\u00a0" /* Unicode nonbreaking space. */
+                        pre:       "\u00a0\u00a0" // Unicode nonbreaking space.
                     };
 
                     yield option;

common/content/services.js

@@ -15,7 +15,7 @@ const Cu = Components.utils;
 
 /**
  * Cached XPCOM services and instances.
- * 
+ *
  * @constructor
  */
 function Services()

common/content/style.js

@@ -246,10 +246,9 @@ function Highlights(name, store, serial)
  */
 function Styles(name, store, serial)
 {
-    /* Can't reference liberator or Components inside Styles --
+    // Can't reference liberator or Components inside Styles --
-     * they're members of the window object, which disappear
+    // they're members of the window object, which disappear
-     * with this window.
+    // with this window.
-     */
     const util = modules.util;
     const sleep = liberator.sleep;
     const storage = modules.storage;

common/content/template.js

@@ -7,7 +7,7 @@ const template = {
 
     map: function map(iter, fn, sep, interruptable)
     {
-        if (iter.length) /* Kludge? */
+        if (iter.length) // FIXME: Kludge?
             iter = util.Array.iterator(iter);
         let ret = <></>;
         let n = 0;
@@ -287,7 +287,7 @@ const template = {
 
     tabular: function tabular(headings, style, iter)
     {
-        /* This might be mind-bogglingly slow. We'll see. */
+        // TODO: This might be mind-bogglingly slow. We'll see.
         // <e4x>
         return this.commandOutput(
             <table>

common/content/ui.js

@@ -28,7 +28,7 @@ the terms of any one of the MPL, the GPL or the LGPL.
 
 /** @scope modules */
 
-/*
+/**
  * This class is used for prompting of user input and echoing of messages
  *
  * it consists of a prompt and command field
@@ -560,11 +560,10 @@ function CommandLine() //{{{
 
         liberator.triggerObserver("echoMultiline", str, highlightGroup);
 
-        /* If it's already XML, assume it knows what it's doing.
+        // If it's already XML, assume it knows what it's doing.
-         * Otherwise, white space is significant.
+        // Otherwise, white space is significant.
-         * The problem elsewhere is that E4X tends to insert new lines
+        // The problem elsewhere is that E4X tends to insert new lines
-         * after interpolated data.
+        // after interpolated data.
-         */
         XML.ignoreWhitespace = typeof str != "xml";
         lastMowOutput = <div class="ex-command-output" style="white-space: nowrap" highlight={highlightGroup}>{template.maybeXML(str)}</div>;
         let output = util.xmlToDom(lastMowOutput, doc);

muttator/content/mail.js

@@ -890,12 +890,13 @@ function Mail() //{{{
             return false;
         },
 
-        /*
+        /**
-         * general-purpose method to find messages
+         * General-purpose method to find messages
-         * @param validatorFunc(msg): return true/false whether msg should be selected or not
+         *
-         * @param canWrap: when true, wraps around folders
+         * @param {function} validatorFunc(msg): return true/false whether msg should be selected or not
-         * @param openThreads: should we open closed threads?
+         * @param {boolean} canWrap: when true, wraps around folders
-         * @param reverse: change direction of searching
+         * @param {boolean} openThreads: should we open closed threads?
+         * @param {boolean} reverse: change direction of searching
          */
         selectMessage: function (validatorFunc, canWrap, openThreads, reverse, count)
         {

vimperator/regressions.js

@@ -28,9 +28,9 @@ var singlelineOutput = document.getElementById("liberator-commandline-command")
 // previous command
 /////////////////////////////////////////////////////////////////////////////////////////
 
-// A series of ex commands or mappings, each with a
+// A series of Ex commands or mappings, each with a
 // function checking whether the command succeeded
-// If the string starts with a ":" it is executed as an ex command, otherwise as a mapping
+// If the string starts with a ":" it is executed as an Ex command, otherwise as a mapping
 // You can also mix commands mappings
 let tests = [
     { cmds: [":!dir"],
@@ -56,7 +56,7 @@ let tests = [
     // testing tab behavior
 ];
 
-// these functions highly depend on the liberator API, so use ex command tests whenever possible
+// these functions highly depend on the liberator API, so use Ex command tests whenever possible
 let functions = [
     function () { return bookmarks.get("").length > 0 }, // will fail for people without bookmarks :( Might want to add one before
     function () { return history.get("").length > 0 }
@@ -120,7 +120,7 @@ commands.addUserCommand(["regr[essions]"],
         // TODO: count (better even range) support to just run test 34 of 102
         // TODO: bang support to either: a) run commands like deleting bookmarks which
         //       should only be done in a clean profile or b) run functions and not
-        //       just ex command tests; Yet to be decided
+        //       just Ex command tests; Yet to be decided
 
         let updateOutputHeight = null;
         function init()