Add some API documentation for Options and others.

common/content/commands.js

@@ -41,14 +41,15 @@ the terms of any one of the MPL, the GPL or the LGPL.
  * @param {function} action The action invoked by this command when executed.
  * @param {Object} extraInfo An optional extra configuration hash. The
  *     following properties are supported.
- *         argCount  - See (@link Command#argCount)
+ *         argCount  - see {@link Command#argCount}
- *         bang      - See (@link Command#bang)
+ *         bang      - see {@link Command#bang}
- *         completer - See (@link Command#completer)
+ *         completer - see {@link Command#completer}
- *         count     - See (@link Command#count)
+ *         count     - see {@link Command#count}
- *         heredoc   - See (@link Command#heredoc)
+ *         heredoc   - see {@link Command#heredoc}
- *         literal   - See (@link Command#literal)
+ *         literal   - see {@link Command#literal}
- *         options   - See (@link Command#options)
+ *         options   - see {@link Command#options}
- *         serial    - See (@link Command#serial)
+ *         serial    - see {@link Command#serial}
+ * @optional
  * @private
  */
 function Command(specs, description, action, extraInfo) //{{{
@@ -91,64 +92,84 @@ function Command(specs, description, action, extraInfo) //{{{
     };
 
     let expandedSpecs = parseSpecs(specs);
-    /** @property {string[]} All of this command's name spacs. e.g., "com[mand]" */
+    /**
+     * @property {string[]} All of this command's name specs. e.g., "com[mand]"
+     */
     this.specs      = specs;
     /** @property {string[]} All of this command's short names, e.g., "com" */
     this.shortNames = expandedSpecs.shortNames;
-    /** @property {string[]} All of this command's long names, e.g., "command" */
+    /**
-    this.longNames  = expandedSpecs.longNames;
+     * @property {string[]} All of this command's long names, e.g., "command"
+     */
+    this.longNames = expandedSpecs.longNames;
 
     /** @property {string} The command's canonical name. */
-    this.name        = this.longNames[0];
+    this.name = this.longNames[0];
     /** @property {string[]} All of this command's long and short names. */
-    this.names       = expandedSpecs.names; // return all command name aliases
+    this.names = expandedSpecs.names; // return all command name aliases
 
     /** @property {string} This command's description, as shown in :exusage */
     this.description = description || "";
-    /** @property {function (Args)} The function called to execute this command. */
+    /**
-    this.action      = action;
+     * @property {function (Args)} The function called to execute this command.
-    /** @property {string} This command's argument count spec. @see Commands#parseArguments */
+     */
-    this.argCount    = extraInfo.argCount || 0;
+    this.action = action;
-    /** @property {function (CompletionContext, Args)} This command's completer. @see CompletionContext */
+    /**
-    this.completer   = extraInfo.completer || null;
+     * @property {string} This command's argument count spec.
+     * @see Commands#parseArguments
+     */
+    this.argCount = extraInfo.argCount || 0;
+    /**
+     * @property {function (CompletionContext, Args)} This command's completer.
+     * @see CompletionContext
+     */
+    this.completer = extraInfo.completer || null;
     /** @property {boolean} Whether this command accepts a here document. */
-    this.hereDoc     = extraInfo.hereDoc || false;
+    this.hereDoc = extraInfo.hereDoc || false;
-    /** @property {Array} The options this command takes. @see Commands@parseArguments */
-    this.options     = extraInfo.options || [];
-    /** @property {boolean} Whether this command may be called with a bang, e.g., :com! */
-    this.bang        = extraInfo.bang || false;
-    /** @property {boolean} Whether this command may be called with a count, e.g., :12bdel */
-    this.count       = extraInfo.count || false;
     /**
-     * @property {boolean} At what index this command's literal
+     * @property {Array} The options this command takes.
-     * arguments begin. For instance, with a value of 2, all arguments
+     * @see Commands@parseArguments
-     * 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
-     * arguments.
      */
-    this.literal     = extraInfo.literal == null ? null : extraInfo.literal;
+    this.options = extraInfo.options || [];
     /**
-     * @property {function} Should return an array of <b>Object</b>s
+     * @property {boolean} Whether this command may be called with a bang,
-     * suitable to be passed to {@link Commands#commandToString}, one
+     *     e.g., :com!
-     * for each past invocation which should be restored on subsequent
-     * @liberator startups.
      */
-    this.serial      = extraInfo.serial;
+    this.bang = extraInfo.bang || false;
+    /**
+     * @property {boolean} Whether this command may be called with a count,
+     *     e.g., :12bdel
+     */
+    this.count = extraInfo.count || false;
+    /**
+     * @property {boolean} At what index this command's literal 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 arguments.
+     */
+    this.literal = extraInfo.literal == null ? null : extraInfo.literal;
+    /**
+     * @property {function} Should return an array of <b>Object</b>s suitable
+     *     to be passed to {@link Commands#commandToString}, one for each past
+     *     invocation which should be restored on subsequent @liberator
+     *     startups.
+     */
+    this.serial = extraInfo.serial;
 
     /**
-     * @property {boolean} Specifies whether this is a user command.
+     * @property {boolean} Specifies whether this is a user command.  User
-     * User commands may be created by plugins, or directly by users,
+     *     commands may be created by plugins, or directly by users, and,
-     * and, unlike basic commands, may be overwritten. Users and
+     *     unlike basic commands, may be overwritten. Users and plugin authors
-     * plugin authors should create only user commands.
+     *     should create only user commands.
      */
-    this.isUserCommand   = extraInfo.isUserCommand || false;
+    this.isUserCommand = extraInfo.isUserCommand || false;
     /**
-     * @property {string} For commands defined via :command, contains
+     * @property {string} For commands defined via :command, contains the Ex
-     * the Ex command line to be executed upon invocation.
+     *     command line to be executed upon invocation.
      */
     this.replacementText = extraInfo.replacementText || null;
-};
+}
 
 Command.prototype = {
 
@@ -286,6 +307,66 @@ function Commands() //{{{
         ArgType("list",    function (arg) arg && arg.split(/\s*,\s*/))
     ];
 
+    // returns [count, parsed_argument]
+    function parseArg(str)
+    {
+        let arg = "";
+        let quote = null;
+        let len = str.length;
+
+        while (str.length && !/^\s/.test(str))
+        {
+            let res;
+
+            switch (QUOTE_STYLE)
+            {
+                case "vim-sucks":
+                    if (res = str.match = str.match(/^()((?:[^\\\s]|\\.)+)((?:\\$)?)/))
+                        arg += res[2].replace(/\\(.)/g, "$1");
+                    break;
+
+                case "vimperator":
+                    if (res = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
+                        arg += res[2].replace(/\\(.)/g, "$1");
+                    else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
+                        arg += eval(res[0] + (res[3] ? "" : '"'));
+                    else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
+                        arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
+                    break;
+
+                case "rc-ish":
+                    if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
+                        arg += res[2].replace(/\\(.)/g, "$1");
+                    else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
+                        arg += eval(res[0] + (res[3] ? "" : '"'));
+                    else if (res = str.match(/^(')((?:[^']|'')*)('?)/))
+                        arg += res[2].replace("''", "'", "g");
+                    break;
+
+                case "pythonesque":
+                    if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
+                        arg += res[2].replace(/\\(.)/g, "$1");
+                    else if (res = str.match(/^(""")((?:.?.?[^"])*)((?:""")?)/))
+                        arg += res[2];
+                    else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
+                        arg += eval(res[0] + (res[3] ? "" : '"'));
+                    else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
+                        arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
+                    break;
+            }
+
+            if (!res)
+                break;
+            if (!res[3])
+                quote = res[1];
+            if (!res[1])
+                quote = res[3];
+            str = str.substr(res[0].length);
+        }
+
+        return [len - str.length, arg, quote];
+    }
+
     function addCommand(command, isUserCommand, replace)
     {
         if (!command) // XXX
@@ -321,29 +402,93 @@ function Commands() //{{{
     const self = {
 
         // FIXME: remove later, when our option handler is better
-        OPTION_ANY:    0, // can be given no argument or an argument of any type,
+        /**
-                          // caller is responsible for parsing the return value
+         * @property The option argument is unspecified. Any argument is
-        OPTION_NOARG:  1,
+         *     accepted and caller is responsible for parsing the return value.
-        OPTION_BOOL:   2,
+         * @final
+         */
+        OPTION_ANY: 0,
+
+        /**
+         * @property The option doesn't accept an argument.
+         * @final
+         */
+        OPTION_NOARG: 1,
+        /**
+         * @property The option accepts a boolean argument.
+         * @final
+         */
+        OPTION_BOOL: 2,
+        /**
+         * @property The option accepts a string argument.
+         * @final
+         */
         OPTION_STRING: 3,
-        OPTION_INT:    4,
+        /**
-        OPTION_FLOAT:  5,
+         * @property The option accepts an integer argument.
-        OPTION_LIST:   6,
+         * @final
+         */
+        OPTION_INT: 4,
+        /**
+         * @property The option accepts a float argument.
+         * @final
+         */
+        OPTION_FLOAT: 5,
+        /**
+         * @property The option accepts a string list argument. E.g. "foo,bar"
+         * @final
+         */
+        OPTION_LIST: 6,
 
+        /**
+         * @property Indicates that no count was specified for this command
+         *     invocation.
+         * @final
+         */
         COUNT_NONE: -1,
-        COUNT_ALL:  -2, // :%...
+        /**
+         * @property Indicates that the full buffer range (1,$) was specified
+         *     for this command invocation.
+         * @final
+         */
+        // FIXME: this isn't a count at all
+        COUNT_ALL: -2, // :%...
 
+        /** @property {Iterator(Command)} @private */
         __iterator__: function ()
         {
             let sorted = exCommands.sort(function (a, b) a.name > b.name);
             return util.Array.itervalues(sorted);
         },
 
+        /**
+         * Adds a new default command.
+         *
+         * @param {string[]} names The names by which this command can be
+         *     invoked. The first name specified is the command's canonical
+         *     name.
+         * @param {string} description A description of the command.
+         * @param {function} action The action invoked by this command.
+         * @param {Object} extra An optional extra configuration hash.
+         * @optional
+         */
         add: function (names, description, action, extra)
         {
             return addCommand(new Command(names, description, action, extra), false, false);
         },
 
+        /**
+         * Adds a new user-defined command.
+         *
+         * @param {string[]} names The names by which this command can be
+         *     invoked. The first name specified is the command's canonical
+         *     name.
+         * @param {string} description A description of the command.
+         * @param {function} action The action invoked by this command.
+         * @param {Object} extra An optional extra configuration hash.
+         * @param {boolean} replace Overwrite an existing command with the same
+         *     canonical name.
+         */
         addUserCommand: function (names, description, action, extra, replace)
         {
             extra = extra || {};
@@ -353,6 +498,13 @@ function Commands() //{{{
             return addCommand(new Command(names, description, action, extra), true, replace);
         },
 
+        /**
+         * Returns the specified command invocation object serialized to
+         * an executable Ex command string.
+         *
+         * @param {Object} args The command invocation object.
+         * @returns {string}
+         */
         commandToString: function (args)
         {
             let res = [args.command + (args.bang ? "!" : "")];
@@ -373,111 +525,96 @@ function Commands() //{{{
             return res.join(" ");
         },
 
+        /**
+         * Returns the command with matching <b>name</b>.
+         *
+         * @param {string} name The name of the command to return. This can be
+         *     any of the command's names.
+         * @returns {Command}
+         */
         get: function (name)
         {
             return exCommands.filter(function (cmd) cmd.hasName(name))[0] || null;
         },
 
+        /**
+         * Returns the user-defined command with matching <b>name</b>.
+         *
+         * @param {string} name The name of the command to return. This can be
+         *     any of the command's names.
+         * @returns {Command}
+         */
         getUserCommand: function (name)
         {
             return exCommands.filter(function (cmd) cmd.isUserCommand && cmd.hasName(name))[0] || null;
         },
 
+        /**
+         * Returns all user-defined commands.
+         *
+         * @returns {Command[]}
+         */
         getUserCommands: function ()
         {
             return exCommands.filter(function (cmd) cmd.isUserCommand);
         },
 
-        // returns [count, parsed_argument]
-        parseArg: function parseArg(str)
-        {
-            let arg = "";
-            let quote = null;
-            let len = str.length;
-
-            while (str.length && !/^\s/.test(str))
-            {
-                let res;
-
-                switch (QUOTE_STYLE)
-                {
-                    case "vim-sucks":
-                        if (res = str.match = str.match(/^()((?:[^\\\s]|\\.)+)((?:\\$)?)/))
-                            arg += res[2].replace(/\\(.)/g, "$1");
-                        break;
-
-                    case "vimperator":
-                        if (res = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
-                            arg += res[2].replace(/\\(.)/g, "$1");
-                        else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
-                            arg += eval(res[0] + (res[3] ? "" : '"'));
-                        else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
-                            arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
-                        break;
-
-                    case "rc-ish":
-                        if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
-                            arg += res[2].replace(/\\(.)/g, "$1");
-                        else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
-                            arg += eval(res[0] + (res[3] ? "" : '"'));
-                        else if (res = str.match(/^(')((?:[^']|'')*)('?)/))
-                            arg += res[2].replace("''", "'", "g");
-                        break;
-
-                    case "pythonesque":
-                        if (res = str.match = str.match(/^()((?:[^\\\s"']|\\.)+)((?:\\$)?)/))
-                            arg += res[2].replace(/\\(.)/g, "$1");
-                        else if (res = str.match(/^(""")((?:.?.?[^"])*)((?:""")?)/))
-                            arg += res[2];
-                        else if (res = str.match(/^(")((?:[^\\"]|\\.)*)("?)/))
-                            arg += eval(res[0] + (res[3] ? "" : '"'));
-                        else if (res = str.match(/^(')((?:[^\\']|\\.)*)('?)/))
-                            arg += res[2].replace(/\\(.)/g, function (n0, n1) /[\\']/.test(n1) ? n1 : n0);
-                        break;
-                }
-
-                if (!res)
-                    break;
-                if (!res[3])
-                    quote = res[1];
-                if (!res[1])
-                    quote = res[3];
-                str = str.substr(res[0].length);
-            }
-
-            return [len - str.length, arg, quote];
-        },
-
-        // in '-quoted strings, only ' and \ itself are escaped
-        // in "-quoted strings, also ", \n and \t are translated
-        // in non-quoted strings everything is taken literally apart from "\ " and "\\"
-        //
-        // @param str: something like "-x=foo -opt=bar arg1 arg2"
-        // "options" is an array [name, type, validator, completions] and could look like:
-        //  options = [[["-force"], OPTION_NOARG],
-        //             [["-fullscreen", "-f"], OPTION_BOOL],
-        //             [["-language"], OPTION_STRING, validateFunc, ["perl", "ruby"]],
-        //             [["-speed"], OPTION_INT],
-        //             [["-acceleration"], OPTION_FLOAT],
-        //             [["-accessories"], OPTION_LIST, null, ["foo", "bar"]],
-        //             [["-other"], OPTION_ANY]];
-        // @param argCount can be:
-        //            "0": no arguments
-        //            "1": exactly one argument
-        //            "+": one or more arguments
-        //            "*": zero or more arguments (default if unspecified)
-        //            "?": zero or one arguments
-        // @param allowUnknownOptions: -foo won't result in an error, if -foo isn't
-        //                             specified in "options"
         // TODO: should it handle comments?
         //     : it might be nice to be able to specify that certain quoting
         //     should be disabled E.g. backslash without having to resort to
-        //     using literal etc
+        //     using literal etc.
+        //     : I'm not sure documenting the returned object here, and
+        //     elsewhere, as type Args rather than simply Object makes sense,
+        //     especially since it is further augmented for use in
+        //     Command#action etc.
+        /**
+         * Parses <b>str</b> for options and plain arguments.
+         *
+         * The returned <b>Args</b> object is an augmented array of arguments.
+         * Any key/value pairs of <b>extra</b> will be available and the
+         * following additional properties:
+         *     -opt       - the value of the option -opt if specified
+         *     string     - the original argument string <b>str</b>
+         *     literalArg - any trailing literal argument
+         *
+         * Quoting rules:
+         *     '-quoted strings   - only ' and \ itself are escaped
+         *     "-quoted strings   - also ", \n and \t are translated
+         *     non-quoted strings - everything is taken literally apart from "\
+         *                          " and "\\"
+         *
+         * @param {string} str The Ex command-line string to parse. E.g.
+         *     "-x=foo -opt=bar arg1 arg2"
+         * @param {Array} options The options accepted. These are specified as
+         *     an array [name, type, validator, completions]. E.g.
+         *     options = [[["-force"], OPTION_NOARG],
+         *                [["-fullscreen", "-f"], OPTION_BOOL],
+         *                [["-language"], OPTION_STRING, validateFunc, ["perl", "ruby"]],
+         *                [["-speed"], OPTION_INT],
+         *                [["-acceleration"], OPTION_FLOAT],
+         *                [["-accessories"], OPTION_LIST, null, ["foo", "bar"]],
+         *                [["-other"], OPTION_ANY]];
+         * @param {string} argCount The number of arguments accepted.
+         *            "0": no arguments
+         *            "1": exactly one argument
+         *            "+": one or more arguments
+         *            "*": zero or more arguments (default if unspecified)
+         *            "?": zero or one arguments
+         * @param {boolean} allowUnknownOptions Whether unspecified options
+         *     should cause an error.
+         * @param {number} literal The index at which any literal arg begins.
+         *     See {@link Command#literal}.
+         * @param {CompletionContext} complete The relevant completion context
+         *     when the args are being parsed for completion.
+         * @param {Object} extra Extra keys to be spliced into the returned
+         *     Args object.
+         * @returns {Args}
+         */
         parseArgs: function (str, options, argCount, allowUnknownOptions, literal, complete, extra)
         {
             function getNextArg(str)
             {
-                let [count, arg, quote] = commands.parseArg(str);
+                let [count, arg, quote] = parseArg(str);
                 if (quote == "\\" && !complete)
                     return [,,,"Trailing \\"];
                 if (quote && !complete)
@@ -737,6 +874,21 @@ function Commands() //{{{
             return args;
         },
 
+        /**
+         * Parses a complete Ex command.
+         *
+         * The parsed string is returned as an Array like
+         * [count, command, bang, args]:
+         *     count   - any count specified
+         *     command - the Ex command name
+         *     bang    - whether the special "bang" version was called
+         *     args    - the commands full argument string
+         * E.g. ":2foo! bar" -> [2, "foo", true, "bar"]
+         *
+         * @param {string} str The Ex command line string.
+         * @returns {Array}
+         */
+        // FIXME: why does this return an Array rather than Object?
         parseCommand: function (str)
         {
             // remove comments
@@ -759,16 +911,37 @@ function Commands() //{{{
             return [count, cmd, !!special, args || ""];
         },
 
-        get complQuote() complQuote,
+        /** @property @private */
+        get complQuote() complQuote, // XXX: needed?
 
-        get quoteArg() quoteArg,
+        /** @property @private */
+        get quoteArg() quoteArg, // XXX: needed?
 
+        /**
+         * Remove the user-defined command with matching <b>name</b>.
+         *
+         * @param {string} name The name of the command to remove. This can be
+         *     any of the command's names.
+         */
         removeUserCommand: function (name)
         {
             exCommands = exCommands.filter(function (cmd) !(cmd.isUserCommand && cmd.hasName(name)));
         },
 
-        // FIXME: still belong here? Also used for autocommand parameters
+        // FIXME: still belong here? Also used for autocommand parameters.
+        /**
+         * Returns a string with all tokens in <b>string</b> matching "<key>"
+         * replaced with "value". Where "key" is a property of the specified
+         * <b>tokens</b> object and "value" is the corresponding value. The
+         * <lt> token can be used to include a literal "<" in the returned
+         * string. Any tokens prefixed with "q-" will be quoted except for
+         * <q-lt> which is treated like <lt>.
+         *
+         * @param {string} str The string with tokens to replace.
+         * @param {Object} tokens A map object whose keys are replaced with its
+         *     values.
+         * @returns {string}
+         */
         replaceTokens: function replaceTokens(str, tokens)
         {
             return str.replace(/<((?:q-)?)([a-zA-Z]+)?>/g, function (match, quote, token)

common/content/editor.js

@@ -1062,7 +1062,8 @@ function Editor() //{{{
         /**
          * Expands an abbreviation in the currently active textbox.
          *
-         * @param {string} filter The mode filter. (@see #addAbbreviation)
+         * @param {string} filter The mode filter.
+         * @see #addAbbreviation
          */
         expandAbbreviation: function (filter)
         {
@@ -1099,10 +1100,10 @@ function Editor() //{{{
         /**
          * Returns all abbreviations matching <b>filter</b> and <b>lhs</b>.
          *
-         * @param {string} filter The mode filter. (@see #addAbbreviation)
+         * @param {string} filter The mode filter.
          * @param {string} lhs The LHS of the abbreviation.
-         *     (@see #addAbbreviation)
          * @returns {Array} The matching abbreviations [mode, lhs, rhs]
+         * @see #addAbbreviation
          */
         getAbbreviations: function (filter, lhs)
         {
@@ -1115,9 +1116,9 @@ function Editor() //{{{
         /**
          * Lists all abbreviations matching <b>filter</b> and <b>lhs</b>.
          *
-         * @param {string} filter The mode filter. (@see #addAbbreviation)
+         * @param {string} filter The mode filter.
          * @param {string} lhs The LHS of the abbreviation.
-         *     (@see #addAbbreviation)
+         * @see #addAbbreviation
          */
         listAbbreviations: function (filter, lhs)
         {
@@ -1143,9 +1144,9 @@ function Editor() //{{{
         /**
          * Deletes all abbreviations matching <b>filter</b> and <b>lhs</b>.
          *
-         * @param {string} filter The mode filter. (@see #addAbbreviation)
+         * @param {string} filter The mode filter.
          * @param {string} lhs The LHS of the abbreviation.
-         *     (@see #addAbbreviation)
+         * @see #addAbbreviation
          */
         removeAbbreviation: function (filter, lhs)
         {
@@ -1196,7 +1197,8 @@ function Editor() //{{{
         /**
          * Removes all abbreviations matching <b>filter</b>.
          *
-         * @param {string} filter The mode filter. (@see #addAbbreviation)
+         * @param {string} filter The mode filter.
+         * @see #addAbbreviation
          */
         removeAllAbbreviations: function (filter)
         {

common/content/hints.js

@@ -136,9 +136,9 @@ function Hints() //{{{
      * If it finds a hint it returns it, if the hint is not the caption of the
      * element it will return showtext=true.
      *
-     * @param {object} elem  The element.
+     * @param {Object} elem  The element.
      * @param {string} tagname  Its tagname.
-     * @param {doc}  The document it is in.
+     * @param {Document} doc  The document it is in.
      *
      * @returns [text, showtext]
      */
@@ -201,9 +201,9 @@ function Hints() //{{{
      *
      * Only called by generate()
      *
-     * @param {object} elem  The <area> element.
+     * @param {Object} elem  The <area> element.
-     * @param {Number} leftpos  The left offset of the image.
+     * @param {number} leftpos  The left offset of the image.
-     * @param {Number} toppos  The top offset of the image.
+     * @param {number} toppos  The top offset of the image.
      * @returns [leftpos, toppos]  The updated offsets.
      */
     function getAreaOffset(elem, leftpos, toppos)
@@ -274,7 +274,7 @@ function Hints() //{{{
      *
      * Pushes the hints into the pageHints object, but does not display them.
      *
-     * @param {object} win  The window,defaults to window.content
+     * @param {Window} win  The window,defaults to window.content
      */
     function generate(win)
     {
@@ -368,7 +368,7 @@ function Hints() //{{{
     /**
      * Toggle the highlight of a hint.
      *
-     * @param {object} elem  The element to toggle.
+     * @param {Object} elem  The element to toggle.
      * @param {boolean} active  Whether it is the currently active hint or not.
      */
     function setClass(elem, active)

common/content/liberator.js

@@ -633,7 +633,6 @@ const liberator = (function () //{{{
         //  "complete"
         //  TODO: "zoom": if the zoom value of the current buffer changed
         //  TODO: move to ui.js?
-        //  Yes --djk
         registerCallback: function (type, mode, func)
         {
             if (!(type in callbacks))

common/content/mappings.js

@@ -41,10 +41,11 @@ the terms of any one of the MPL, the GPL or the LGPL.
  * @param {function} action The action invoked by each key sequence.
  * @param {Object} extraInfo An optional extra configuration hash. The
  *     following properties are supported.
- *         flags   - See (@link Map#flags)
+ *         flags   - see {@link Map#flags}
- *         noremap - See (@link Map#noremap)
+ *         noremap - see {@link Map#noremap}
- *         rhs     - See (@link Map#rhs)
+ *         rhs     - see {@link Map#rhs}
- *         silent  - See (@link Map#silent)
+ *         silent  - see {@link Map#silent}
+ * @optional
  * @private
  */
 function Map(modes, keys, description, action, extraInfo) //{{{
@@ -59,7 +60,8 @@ function Map(modes, keys, description, action, extraInfo) //{{{
     /** @property {function (number)} The function called to execute this mapping. */
     this.action = action;
 
-    /** @property {number} See (@link Mappings#flags) */
+    /** @property {number} @see Mappings#flags */
+    // FIXME: flags is incongruent with the other properties
     this.flags = extraInfo.flags || 0;
     /** @property {string} This mapping's description, as shown in :viusage. */
     this.description = description || "";
@@ -69,7 +71,7 @@ function Map(modes, keys, description, action, extraInfo) //{{{
     this.noremap = extraInfo.noremap || false;
     /** @property {boolean} Whether any output from the mapping should be echoed on the command line. */
     this.silent = extraInfo.silent || false;
-};
+}
 
 Map.prototype = {
 
@@ -329,6 +331,7 @@ function Mappings() //{{{
     return {
 
         // NOTE: just normal mode for now
+        /** @property {Iterator(Map)} @private */
         __iterator__: function () mappingsIterator([modes.NORMAL], main),
 
         // used by :mkvimperatorrc to save mappings
@@ -342,7 +345,7 @@ function Mappings() //{{{
         getUserIterator: function (mode) mappingsIterator(mode, user),
 
         /**
-         * Add a new default key mapping.
+         * Adds a new default key mapping.
          *
          * @param {number[]} modes The modes that this mapping applies to.
          * @param {string[]} keys The key sequences which are bound to
@@ -350,6 +353,7 @@ function Mappings() //{{{
          * @param {string} description A description of the key mapping.
          * @param {function} action The action invoked by each key sequence.
          * @param {Object} extra An optional extra configuration hash.
+         * @optional
          */
         add: function (modes, keys, description, action, extra)
         {
@@ -357,14 +361,16 @@ function Mappings() //{{{
         },
 
         /**
-         * Add a new user-defined key mapping.
+         * Adds a new user-defined key mapping.
          *
          * @param {number[]} modes The modes that this mapping applies to.
          * @param {string[]} keys The key sequences which are bound to
          *     <b>action</b>.
          * @param {string} description A description of the key mapping.
          * @param {function} action The action invoked by each key sequence.
-         * @param {Object} extra An optional extra configuration hash.
+         * @param {Object} extra An optional extra configuration hash (see
+         *     {@link Map#extraInfo}).
+         * @optional
          */
         addUserMap: function (modes, keys, description, action, extra)
         {

common/content/options.js

@@ -30,30 +30,92 @@ the terms of any one of the MPL, the GPL or the LGPL.
 
 // do NOT create instances of this class yourself, use the helper method
 // options.add() instead
+/**
+ * A class representing configuration options. Instances are created by the
+ * {@link Options} class.
+ *
+ * @param {string[]} names The names by which this option is identified.
+ * @param {string} description A short one line description of the option.
+ * @param {string} type The option's value data type (see {@link Option#type}).
+ * @param {string} defaultValue The default value for this option.
+ * @param {Object} extraInfo An optional extra configuration hash. The
+ *     following properties are supported.
+ *         scope     - see {@link Option#scope}
+ *         setter    - see {@link Option#setter}
+ *         getter    - see {@link Option#getter}
+ *         completer - see {@link Option#completer}
+ *         valdator  - see {@link Option#validator}
+ *         checkHas  - see {@link Option#checkHas}
+ * @optional
+ * @private
+ */
 function Option(names, description, type, defaultValue, extraInfo) //{{{
 {
     if (!extraInfo)
         extraInfo = {};
 
+    /** @property {string} The option's canonical name. */
     this.name = names[0];
+    /** @property {string[]} All names by which this option is identified. */
     this.names = names;
+    /**
+     * @property {string} The option's data type. One of:
+     *     "boolean"    - Boolean E.g. true
+     *     "number"     - Integer E.g. 1
+     *     "string"     - String E.g. "Vimperator"
+     *     "charlist"   - Character list E.g. "rb"
+     *     "stringlist" - String list E.g. "homepage,quickmark,tabopen,paste"
+     */
     this.type = type;
-    this.scope = (extraInfo.scope & options.OPTION_SCOPE_BOTH) ||
+    /**
-                 options.OPTION_SCOPE_GLOBAL;
+     * @property {number} The scope of the option. This can be local, global,
-                 // XXX set to BOTH by default someday? - kstep
+     * or both.
+     * @see Options#OPTION_SCOPE_LOCAL
+     * @see Options#OPTION_SCOPE_GLOBAL
+     * @see Options#OPTION_SCOPE_BOTH
+     */
+    this.scope = (extraInfo.scope & options.OPTION_SCOPE_BOTH) || options.OPTION_SCOPE_GLOBAL; // XXX set to BOTH by default someday? - kstep
+    /**
+     * @property {string} This option's description, as shown in :optionusage.
+     */
     this.description = description || "";
 
-    // "", 0 are valid default values
+    /**
-    this.defaultValue = (defaultValue === undefined) ? null : defaultValue;
+     * @property {value} The option's default value. This value will be used
+     * unless the option is explicitly set either interactively or in an RC
+     * file or plugin.
+     */
+    this.defaultValue = (defaultValue === undefined) ? null : defaultValue; // "", 0 are valid default values
 
+    /**
+     * @property {function} The function called when the option value is set.
+     */
     this.setter = extraInfo.setter || null;
+    /**
+     * @property {function} The function called when the option value is read.
+     */
     this.getter = extraInfo.getter || null;
+    /**
+     * @property {function(CompletionContext, Args)} This option's completer.
+     * @see CompletionContext
+     */
     this.completer = extraInfo.completer || null;
+    /**
+     * @property {function} The function called to validate the option's value
+     * when set.
+     */
     this.validator = extraInfo.validator || null;
+    /**
+     * @property The function called to determine whether the option already
+     * contains a specified value.
+     * @see #has
+     */
     this.checkHas = extraInfo.checkHas || null;
-
+    /**
-    // this property is set to true whenever the option is first set
+     * @property {boolean} Set to true whenever the option is first set. This
-    // useful to see whether it was changed by some rc file
+     * is useful to see whether it was changed from its default value
+     * interactively or by some RC file.
+     */
     this.hasChanged = false;
 
     // add no{option} variant of boolean {option} to this.names
@@ -70,10 +132,20 @@ function Option(names, description, type, defaultValue, extraInfo) //{{{
     if (this.globalvalue == undefined)
         this.globalvalue = this.defaultValue;
 }
+
 Option.prototype = {
+
+    /** @property {value} The option's global value. @see #scope */
     get globalvalue() options.store.get(this.name),
     set globalvalue(val) { options.store.set(this.name, val); },
 
+    /**
+     * Returns <b>value</b> as an array of parsed values if the option type is
+     * "charlist" or "stringlist" or else unchanged.
+     *
+     * @param {value} value The option value.
+     * @returns {value|string[]}
+     */
     parseValues: function (value)
     {
         if (this.type == "stringlist")
@@ -83,6 +155,13 @@ Option.prototype = {
         return value;
     },
 
+    /**
+     * Returns <b>values</b> packed in the appropriate format for the option
+     * type.
+     *
+     * @param {value|string[]} values The option value.
+     * @returns {value}
+     */
     joinValues: function (values)
     {
         if (this.type == "stringlist")
@@ -92,16 +171,41 @@ Option.prototype = {
         return values;
     },
 
+    /** @property {value|string[]} The option value or array of values. */
     get values() this.parseValues(this.value),
     set values(values) this.setValues(values, this.scope),
 
+    /**
+     * Returns the option's value as an array of parsed values if the option
+     * type is "charlist" or "stringlist" or else the simple value.
+     *
+     * @param {number} scope The scope to return these values from (see
+     *     {@link Option#scope}).
+     * @returns {value|string[]}
+     */
     getValues: function (scope) this.parseValues(this.get(scope)),
 
+    /**
+     * Sets the option's value from an array of values if the option type is
+     * "charlist" or "stringlist" or else the simple value.
+     *
+     * @param {number} scope The scope to apply these values to (see
+     *     {@link Option#scope}).
+     */
     setValues: function (values, scope)
     {
         this.set(this.joinValues(values), scope || this.scope);
     },
 
+    /**
+     * Returns the value of the option in the specified <b>scope</b>. The
+     * (@link Option#getter) callback, if it exists, is invoked with this value
+     * before it is returned.
+     *
+     * @param {number} scope The scope to return this value from (see
+     *     {@link Option#scope}).
+     * @returns {value}
+     */
     get: function (scope)
     {
         if (scope)
@@ -127,6 +231,15 @@ Option.prototype = {
         return aValue;
     },
 
+    /**
+     * Sets the option value to <b>newValue</b> for the specified <b>scope</b>.
+     * The (@link Option#setter) callback, if it exists, is invoked with
+     * <b>newValue</b>.
+     *
+     * @param {value} newValue The option's new value.
+     * @param {number} scope The scope to apply this value to (see
+     *     {@link Option#scope}).
+     */
     set: function (newValue, scope)
     {
         scope = scope || this.scope;
@@ -153,9 +266,19 @@ Option.prototype = {
         this.hasChanged = true;
     },
 
+    /**
+     * @property {value} The option's current value. The option's local value,
+     * or if no local value is set, this is equal to the (@link #globalvalue).
+     */
     get value() this.get(),
     set value(val) this.set(val),
 
+    /**
+     * Returns whether the option value contains one or more of the specified
+     * arguments.
+     *
+     * @returns {boolean}
+     */
     has: function ()
     {
         let self = this;
@@ -167,8 +290,18 @@ Option.prototype = {
         return Array.some(arguments, function (val) test(val));
     },
 
+    /**
+     * Returns whether this option is identified by <b>name</b>.
+     *
+     * @param {string} name
+     * @returns {boolean}
+     */
     hasName: function (name) this.names.indexOf(name) >= 0,
 
+    /**
+     * Returns whether the specified <b>values</b> are valid for this option.
+     * @see Option#validator
+     */
     isValidValue: function (values)
     {
         if (this.validator)
@@ -177,11 +310,23 @@ Option.prototype = {
             return true;
     },
 
+    /**
+     * Resets the option to its default value.
+     */
     reset: function ()
     {
         this.value = this.defaultValue;
     },
 
+    /**
+     * Sets the option's value using the specified set <b>operator</b>.
+     *
+     * @param {string} operator The set operator.
+     * @param {value|string[]} values The value (or values) to apply.
+     * @param {number} scope The scope to apply this value to (see
+     *     {@link #scope}).
+     * @param {boolean} invert Whether this is an invert boolean operation.
+     */
     op: function (operator, values, scope, invert)
     {
         let newValue = null;
@@ -281,15 +426,23 @@ Option.prototype = {
         this.setValues(newValue, scope);
     }
 };
-  // TODO: Run this by default?
+
+// TODO: Run this by default?
+/**
+ * Validates the specified <b>values</b> against values generated by the
+ * option's completer function.
+ *
+ * @param {value|string[]} values The value or array of values to validate.
+ * @returns {boolean}
+ */
 Option.validateCompleter = function (values)
 {
+    liberator.log(values instanceof Array)
     let context = CompletionContext("");
     let res = context.fork("", 0, this, this.completer);
     if (!res)
         res = context.allItems.items.map(function (item) [item.text]);
-    return Array.concat(values).every(
+    return Array.concat(values).every(function (value) res.some(function (item) item[0] == value));
-        function (value) res.some(function (item) item[0] == value));
 }; //}}}
 
 /**
@@ -807,16 +960,33 @@ function Options() //{{{
 
     const self = {
 
+        /**
+         * @property {number} Global option scope.
+         * @final
+         */
         OPTION_SCOPE_GLOBAL: 1,
-        OPTION_SCOPE_LOCAL:  2,
-        OPTION_SCOPE_BOTH:   3,
 
+        /**
+         * @property {number} Local option scope. Options in this scope only
+         *     apply to the current tab/buffer.
+         * @final
+         */
+        OPTION_SCOPE_LOCAL: 2,
+
+        /**
+         * @property {number} Both local and global option scope.
+         * @final
+         */
+        OPTION_SCOPE_BOTH: 3,
+
+        /** @property {Iterator(Option)} @private */
         __iterator__: function ()
         {
             let sorted = [o for ([i, o] in Iterator(optionHash))].sort(function (a, b) String.localeCompare(a.name, b.name));
             return (v for ([k, v] in Iterator(sorted)));
         },
 
+        /** @property {Object} Observes preference value changes. */
         prefObserver: {
             register: function ()
             {
@@ -848,6 +1018,18 @@ function Options() //{{{
              }
         },
 
+        /**
+         * Adds a new option.
+         *
+         * @param {string[]} names All names for the option.
+         * @param {string} description A description of the option.
+         * @param {string} type The option type (see {@link Option#type}).
+         * @param {value} defaultValue The option's default value.
+         * @param {Object} extra An optional extra configuration hash (see
+         *     {@link Map#extraInfo}).
+         * @optional
+         * @returns {boolean} Whether the option was created.
+         */
         add: function (names, description, type, defaultValue, extraInfo)
         {
             if (!extraInfo)
@@ -873,6 +1055,14 @@ function Options() //{{{
             return true;
         },
 
+        /**
+         * Returns the option with <b>name</b> in the specified <b>scope</b>.
+         *
+         * @param {string} name The option's name.
+         * @param {number} scope The option's scope (see {@link Option#scope}).
+         * @optional
+         * @returns {Option} The matching option.
+         */
         get: function (name, scope)
         {
             if (!scope)
@@ -890,6 +1080,15 @@ function Options() //{{{
             return null;
         },
 
+        /**
+         * Lists all options in <b>scope</b> or only those with changed values
+         * if <b>onlyNonDefault</b> is specified.
+         *
+         * @param {boolean} onlyNonDefault Limit the list to prefs with a
+         *     non-default value.
+         * @param {number} scope Only list options in this scope (see
+         *     {@link Option#scope}).
+         */
         list: function (onlyNonDefault, scope)
         {
             if (!scope)
@@ -929,6 +1128,16 @@ function Options() //{{{
             commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
         },
 
+        /**
+         * Lists all preferences matching <b>filter</b> or only those with
+         * changed values if <b>onlyNonDefault</b> is specified.
+         *
+         * @param {boolean} onlyNonDefault Limit the list to prefs with a
+         *     non-default value.
+         * @param {string} filter The list filter. A null filter lists all
+         *     prefs.
+         * @optional
+         */
         listPrefs: function (onlyNonDefault, filter)
         {
             if (!filter)
@@ -961,6 +1170,15 @@ function Options() //{{{
             commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
         },
 
+        /**
+         * Parses a :set command.
+         *
+         * @param {string} args The :set command's argument string.
+         * @param {Object} modifiers A hash of parsing modifiers. These are:
+         *     scope - see {@link Option#scope}
+         * @optional
+         * @returns {Object} The parsed command object.
+         */
         parseOpt: function parseOpt(args, modifiers)
         {
             let ret = {};
@@ -1005,15 +1223,29 @@ function Options() //{{{
             return ret;
         },
 
+        /** @property {Object} The options store. */
         get store() storage.options,
 
+        /**
+         * Returns the value of the preference <b>name</b>.
+         *
+         * @param {string} name The preference name.
+         * @param {value} forcedDefault The the default value for this
+         *     preference. Used for internal liberator preferences.
+         */
         getPref: function (name, forcedDefault)
         {
             return loadPreference(name, forcedDefault);
         },
 
-        // Set a pref, but warn the user if it's changed from its default
+        /**
-        // value.
+         * Sets the preference <b>name</b> to </b>value</b> but warns the user
+         * if the value is changed from its default.
+         *
+         * @param {string} name The preference name.
+         * @param {value} value The new preference value.
+         */
+        // FIXME: Well it used to. I'm looking at you mst! --djk
         safeSetPref: function (name, value)
         {
             let val = loadPreference(name, null, false);
@@ -1025,11 +1257,22 @@ function Options() //{{{
             storePreference(SAVED + name, value);
         },
 
+        /**
+         * Sets the preference <b>name</b> to </b>value</b>.
+         *
+         * @param {string} name The preference name.
+         * @param {value} value The new preference value.
+         */
         setPref: function (name, value)
         {
             storePreference(name, value);
         },
 
+        /**
+         * Resets the preference <b>name</b> to its default value.
+         *
+         * @param {string} name The preference name.
+         */
         resetPref: function (name)
         {
             try
@@ -1042,7 +1285,11 @@ function Options() //{{{
             }
         },
 
-        // this works only for booleans
+        /**
+         * Toggles the value of the boolean preference <b>name</b>.
+         *
+         * @param {string} name The preference name.
+         */
         invertPref: function (name)
         {
             if (services.get("pref").getPrefType(name) == Ci.nsIPrefBranch.PREF_BOOL)
@@ -1079,7 +1326,7 @@ function Options() //{{{
          * previous values.
          *
          * @param {function} fn The function to call.
-         * @param {object} fn The 'this' object with which to call <b>fn</b>
+         * @param {Object} fn The 'this' object with which to call <b>fn</b>
          * @see #pushContext
          * @see #popContext
          */

common/content/tabs.js

@@ -1229,7 +1229,7 @@ function Tabs() //{{{
         // shouldn't be one yet.
         /**
          * Called on each TabSelect event to update the tab selection history.
-         * See (@link tabs.alternate).
+         * @see tabs#alternate
          */
         updateSelectionHistory: function ()
         {

common/content/ui.js

@@ -1220,7 +1220,7 @@ function CommandLine() //{{{
          *
          * @param {string} prompt The input prompt to use.
          * @param {function(string)} callback
-         * @param {object} extra
+         * @param {Object} extra
          * @... {function} onChange - A function to be called with the current
          *     input every time it changes.
          * @... {function(CompletionContext)} completer - A completion function