Document some more crap.

2 files changed, 106 insertions, 6 deletions

diff --git a/common/content/buffer.js b/common/content/buffer.js
index b4d5fd78..c14c599d 100644
--- a/common/content/buffer.js
+++ b/common/content/buffer.js
@@ -1640,6 +1640,15 @@ function Marks() //{{{
 
     return {
 
+        /**
+         * Add a named for the current buffer, at its current position. If
+         * mark matches [A-Z], it's considered a URL mark, and will jump to
+         * the same position at the same URL no matter what buffer it's
+         * 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
+         */
         // TODO: add support for frameset pages
         add: function (mark)
         {
@@ -1672,6 +1681,15 @@ function Marks() //{{{
             }
         },
 
+        /**
+         * Remove all marks matching <b>filter</b>. If <b>special</b> is
+         * given, removes all local marks.
+         *
+         * @param {string} filter A string containing one character for each
+         *     mark to be removed.
+         * @param {boolean} special Whether to delete all local marks.
+         */
+        // FIXME: Shouldn't special be replaced with a null filter?
         remove: function (filter, special)
         {
             if (special)
@@ -1682,20 +1700,24 @@ function Marks() //{{{
             }
             else
             {
-                let pattern = new RegExp("[" + filter.replace(/\s+/g, "") + "]");
                 for (let [mark,] in urlMarks)
                 {
-                    if (pattern.test(mark))
+                    if (filter.indexOf(mark) >= 0)
                         removeURLMark(mark);
                 }
                 for (let [mark,] in localMarks)
                 {
-                    if (pattern.test(mark))
+                    if (filter.indexOf(mark) >= 0)
                         removeLocalMark(mark);
                 }
             }
         },
 
+        /**
+         * Jumps to the named mark. See {@link #add}
+         *
+         * @param {string} mark The mark to jump to.
+         */
         jumpTo: function (mark)
         {
             let ok = false;
@@ -1751,6 +1773,11 @@ function Marks() //{{{
                 liberator.echoerr("E20: Mark not set"); // FIXME: move up?
         },
 
+        /**
+         * List all marks matching <b>filter</b>.
+         *
+         * @param {string} filter
+         */
         list: function (filter)
         {
             let marks = getSortedMarks();
diff --git a/common/content/commands.js b/common/content/commands.js
index d357918d..356960cc 100644
--- a/common/content/commands.js
+++ b/common/content/commands.js
@@ -28,6 +28,12 @@ the terms of any one of the MPL, the GPL or the LGPL.
 
 /** @scope modules */
 
+/**
+ * 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) //{{{
@@ -72,31 +78,81 @@ function Command(specs, description, action, extraInfo) //{{{
         return { names: names, longNames: longNames, shortNames: shortNames };
     };
 
+    // return the primary command name (the long name of the first spec listed)
+    /** @property {string} The command's cannonical name. */
+    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
+
     let expandedSpecs = parseSpecs(specs);
+    /** @property {string[]} All of this command's name spacs. 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;
 
-    // return the primary command name (the long name of the first spec listed)
-    this.name        = this.longNames[0];
-    this.names       = expandedSpecs.names; // return all command name aliases
+    /** @property {string} This command's description, as shown in :exinfo */
     this.description = description || "";
+    /** @property {function (Args)} The function called to execute this command. */
     this.action      = action;
+    /** @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;
+    /** @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
+     * 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.
+     * User commands may be created by plugins, or directly by users,
+     * and, unlike basic commands, may be overwritten. Users and
+     * plugin authors should create only user commands.
+     */
     this.isUserCommand   = extraInfo.isUserCommand || false;
+    /**
+     * @property {string} For commands defined via :command, contains
+     * the EX command line to be executed upon invocation.
+     */
     this.replacementText = extraInfo.replacementText || null;
 };
 
 Command.prototype = {
 
+    /**
+     * Execute this command.
+     *
+     * @param {Args} args The parsed args to be passed to
+     *     {@link #action}.
+     * @param {boolean} bang @deprecated Whether this command was
+     *     executed with a trailing !.
+     * @param {number} count @deprecated Whether this command was
+     *     executed a leading count.
+     * @param modifiers Any modifiers to be passed to 
+     *     {@link action}
+     */
     execute: function (args, bang, count, modifiers)
     {
         // XXX
@@ -130,6 +186,11 @@ Command.prototype = {
         exec(args);
     },
 
+    /**
+     * Returns whether this command may be invoked via <b>name</b>.
+     *
+     * @param {string} name
+     */
     hasName: function (name)
     {
         for (let [,spec] in Iterator(this.specs))
@@ -145,6 +206,18 @@ Command.prototype = {
         return false;
     },
 
+    /**
+     * A helper function to parse an argument string.
+     *
+     * @param {string} args The argument string to parse.
+     * @param {CompletionContext} complete A completion context.
+     *     Non-null when the arguments are being parsed for completion
+     *     purposes.
+     * @param {Object} extra Extra keys to be spliced into the
+     *     returned Args object.
+     * @returns Args
+     * @see Commands#parseArgs
+     */
     parseArgs: function (args, complete, extra) commands.parseArgs(args, this.options, this.argCount, false, this.literal, complete, extra)
 
 }; //}}}