Add some rough documentation for Mappings.

Someone should really add some polished documentation.

common/content/commands.js

@@ -34,6 +34,21 @@ the terms of any one of the MPL, the GPL or the LGPL.
  * A class representing Ex commands. Instances are created by
  * the {@link Commands} class.
  *
+ * @param {string[]} specs The names by which this command can be invoked.
+ *     These are specified in the form "com[mand]" where "com" is a unique
+ *     command name prefix.
+ * @param {string} description A short one line description of the command.
+ * @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)
+ *         bang      - See (@link Command#bang)
+ *         completer - See (@link Command#completer)
+ *         count     - See (@link Command#count)
+ *         heredoc   - See (@link Command#heredoc)
+ *         literal   - See (@link Command#literal)
+ *         options   - See (@link Command#options)
+ *         serial    - See (@link Command#serial)
  * @private
  */
 function Command(specs, description, action, extraInfo) //{{{
@@ -91,7 +106,7 @@ function Command(specs, description, action, extraInfo) //{{{
     /** @property {string[]} All of this command's long and short names. */
     this.names       = expandedSpecs.names; // return all command name aliases
 
-    /** @property {string} This command's description, as shown in :exinfo */
+    /** @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;

common/content/completion.js

@@ -46,7 +46,6 @@ the terms of any one of the MPL, the GPL or the LGPL.
  * @author Kris Maglione <maglione.k@gmail.com>
  * @constructor
  */
-
 function CompletionContext(editor, name, offset) //{{{
 {
     if (!(this instanceof arguments.callee))

common/content/mappings.js

@@ -30,33 +30,71 @@ 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
 // mappings.add() instead
-function Map(modes, cmds, description, action, extraInfo) //{{{
+/**
+ * A class representing key mappings. Instances are created by the
+ * {@link Mappings} class.
+ *
+ * @param {number[]} modes The modes in which this mapping is active.
+ * @param {string[]} keys The key sequences which are bound to
+ *     <b>action</b>.
+ * @param {string} description A short one line description of the key mapping.
+ * @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)
+ *         noremap - See (@link Map#noremap)
+ *         rhs     - See (@link Map#rhs)
+ *         silent  - See (@link Map#silent)
+ * @private
+ */
+function Map(modes, keys, description, action, extraInfo) //{{{
 {
-    if (!modes || (!cmds || !cmds.length) || !action)
+    if (!modes || (!keys || !keys.length) || !action)
         return null;
 
     if (!extraInfo)
         extraInfo = {};
 
+    /** @property {number[]} All of the modes for which this mapping applies. */
     this.modes = modes;
-    // only store keysyms with uppercase modifier strings
+    /** @property {string[]} All of this mapping's names (key sequences). */
-    this.names = cmds.map(function (cmd) cmd.replace(/[casm]-/g, String.toUpperCase));
+    this.names = keys.map(function (cmd) cmd.replace(/[casm]-/g, String.toUpperCase)); // only store keysyms with uppercase modifier strings
+    /** @property {function (number)} The function called to execute this mapping. */
     this.action = action;
 
+    /** @property {number} See (@link Mappings#flags) */
     this.flags = extraInfo.flags || 0;
+    /** @property {string} This mapping's description, as shown in :viusage. */
     this.description = description || "";
+    /** @property {string} The literal RHS expansion of this mapping. */
     this.rhs = extraInfo.rhs || null;
+    /** @property {boolean} Whether the RHS of the mapping should expand mappings recursively. */
     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 = {
 
-    hasName: function (name)
+    /**
-    {
+     * Returns whether this mapping can be invoked by a key sequence matching
-        return this.names.indexOf(name) >= 0;
+     * <b>name</b>.
-    },
+     *
+     * @param {string} name The name to query.
+     * @returns {boolean}
+     */
+    hasName: function (name) this.names.indexOf(name) >= 0,
 
+    /**
+     * Execute the action for this mapping.
+     *
+     * @param {string} motion The motion argument if accepted by this mapping.
+     *     E.g. "w" for "dw"
+     * @param {number} count The associated count. E.g. "5" for "5j"
+     * @default -1
+     * @param {string} argument The normal argument if accepted by this
+     *     mapping. E.g. "a" for "ma"
+     */
     execute: function (motion, count, argument)
     {
         let args = [];
@@ -100,9 +138,9 @@ function Mappings() //{{{
     {
         let where = userMap ? user : main;
         map.modes.forEach(function (mode) {
-                if (!(mode in where))
+            if (!(mode in where))
-                    where[mode] = [];
+                where[mode] = [];
-                where[mode].push(map);
+            where[mode].push(map);
         });
     }
 
@@ -255,6 +293,7 @@ function Mappings() //{{{
     /////////////////////////////////////////////////////////////////////////////{{{
 
     addMapCommands("",  [modes.NORMAL, modes.VISUAL], "");
+
     for (let mode in modes.mainModes)
         if (mode.char)
             addMapCommands(mode.char,
@@ -296,13 +335,40 @@ function Mappings() //{{{
         __iterator__: function () mappingsIterator([modes.NORMAL], main),
 
         // used by :mkvimperatorrc to save mappings
+        /**
+         * Returns a user-defined mappings iterator for the specified
+         * <b>mode</b>.
+         *
+         * @param {number} mode The mode to return mappings from.
+         * @returns {Iterator(Map)}
+         */
         getUserIterator: function (mode) mappingsIterator(mode, user),
 
+        /**
+         * Add 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
+         *     <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.
+         */
         add: function (modes, keys, description, action, extra)
         {
             addMap(new Map(modes, keys, description, action, extra), false);
         },
 
+        /**
+         * Add 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.
+         */
         addUserMap: function (modes, keys, description, action, extra)
         {
             keys = keys.map(expandLeader);
@@ -318,20 +384,41 @@ function Mappings() //{{{
             addMap(map, true);
         },
 
+        /**
+         * Returns the map from <b>mode</b> named <b>cmd</b>.
+         *
+         * @param {number} mode The mode to search.
+         * @param {string} cmd The map name to match.
+         * @returns {Map}
+         */
         get: function (mode, cmd)
         {
             mode = mode || modes.NORMAL;
             return getMap(mode, cmd, user) || getMap(mode, cmd, main);
         },
 
+        /**
+         * Returns the default map from <b>mode</b> named <b>cmd</b>.
+         *
+         * @param {number} mode The mode to search.
+         * @param {string} cmd The map name to match.
+         * @returns {Map}
+         */
         getDefault: function (mode, cmd)
         {
             mode = mode || modes.NORMAL;
             return getMap(mode, cmd, main);
         },
 
-        // returns an array of mappings with names which START with "cmd" (but are NOT "cmd")
+        /**
-        getCandidates: function (mode, cmd)
+         * Returns an array of maps with names starting with but not equal to
+         * <b>prefix</b>.
+         *
+         * @param {number} mode The mode to search.
+         * @param {string} prefix The map prefix string to match.
+         * @returns {Map[]}
+         */
+        getCandidates: function (mode, prefix)
         {
             let mappings = user[mode].concat(main[mode]);
             let matches = [];
@@ -340,10 +427,10 @@ function Mappings() //{{{
             {
                 for (let [,name] in Iterator(map.names))
                 {
-                    if (name.indexOf(cmd) == 0 && name.length > cmd.length)
+                    if (name.indexOf(prefix) == 0 && name.length > prefix.length)
                     {
                         // for < only return a candidate if it doesn't look like a <c-x> mapping
-                        if (cmd != "<" || !/^<.+>/.test(name))
+                        if (prefix != "<" || !/^<.+>/.test(name))
                             matches.push(map);
                     }
                 }
@@ -352,28 +439,57 @@ function Mappings() //{{{
             return matches;
         },
 
+        /*
+         * Returns the map leader string used to replace the special token
+         * "<Leader>" when user mappings are defined.
+         *
+         * @returns {string}
+         */
+        // FIXME: property
         getMapLeader: function ()
         {
             let leaderRef = liberator.variableReference("mapleader");
             return leaderRef[0] ? leaderRef[0][leaderRef[1]] : "\\";
         },
 
-        // returns whether the user added a custom user map
+        /**
-        hasMap: function (mode, cmd)
+         * Returns whether there is a user-defined mapping <b>cmd</b> for the
-        {
+         * specified <b>mode</b>.
-            return user[mode].some(function (map) map.hasName(cmd));
+         *
-        },
+         * @param {number} mode The mode to search.
+         * @param {string} cmd The candidate key mapping.
+         * @returns {boolean}
+         */
+        hasMap: function (mode, cmd) user[mode].some(function (map) map.hasName(cmd)),
 
+        /**
+         * Remove the user-defined mapping named <b>cmd</b> for <b>mode</b>.
+         *
+         * @param {number} mode The mode to search.
+         * @param {string} cmd The map name to match.
+         */
         remove: function (mode, cmd)
         {
             removeMap(mode, cmd);
         },
 
+        /**
+         * Remove all user-defined mappings for <b>mode</b>.
+         *
+         * @param {number} mode The mode to remove all mappings from.
+         */
         removeAll: function (mode)
         {
             user[mode] = [];
         },
 
+        /**
+         * Lists all user-defined mappings matching <b>filter</b> for the
+         * specified <b>modes</b>.
+         *
+         * @param {number[]} modes An array of modes to search.
+         * @param {string} filter The filter string to match.
+         */
         list: function (modes, filter)
         {
             let modeSign = "";
@@ -413,7 +529,6 @@ function Mappings() //{{{
             }
             commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE);
         }
-
     };
     //}}}
 }; //}}}