Add some more rough source documentation.

common/content/buffer.js

@@ -41,6 +41,7 @@ function Buffer() //{{{
     ////////////////////////////////////////////////////////////////////////////////
     ////////////////////// PRIVATE SECTION /////////////////////////////////////////
     /////////////////////////////////////////////////////////////////////////////{{{
+
     /* FIXME: This doesn't belong here. */
     let mainWindowID = config.mainWindowID || "main-window";
     let fontSize = util.computedStyle(document.getElementById(mainWindowID)).fontSize;
@@ -813,8 +814,8 @@ function Buffer() //{{{
     return {
 
         /**
-         * The alternative stylesheets for the current buffer. Only
+         * @property {Array} The alternative stylesheets for the current
-         * returns stylesheets for the 'screen' media type.
+         *     buffer. Only returns stylesheets for the 'screen' media type.
          */
         get alternateStyleSheets()
         {
@@ -832,10 +833,11 @@ function Buffer() //{{{
         get pageInfo() pageInfo,
 
         /**
-         * Returns whether the buffer is loaded. Values may be:
+         * @property {number} A value indicating whether the buffer is loaded.
-         *   0 - Loading.
+         *     Values may be:
-         *   1 - Fully loaded.
+         *         0 - Loading.
-         *   2 - Load failed.
+         *         1 - Fully loaded.
+         *         2 - Load failed.
          */
         get loaded()
         {
@@ -850,8 +852,8 @@ function Buffer() //{{{
         },
 
         /**
-         * The last focused input field in the buffer. Used by the
+         * @property {Object} The last focused input field in the buffer. Used
-         * "gi" key binding.
+         *     by the "gi" key binding.
          */
         get lastInputField()
         {
@@ -866,21 +868,24 @@ function Buffer() //{{{
         },
 
         /**
-         * The current top-level document's URL.
+         * @property {string} The current top-level document's URL.
          */
         get URL()
         {
             return window.content.document.location.href;
         },
 
+        /**
+         * @property {number} The buffer's height in pixels.
+         */
         get pageHeight()
         {
             return window.content.innerHeight;
         },
 
         /**
-         * The current browser's text zoom level, as a percentage with
+         * @property {number} The current browser's text zoom level, as a
-         * 100 as 'normal'. Only affects text size.
+         *     percentage with 100 as 'normal'. Only affects text size.
          */
         get textZoom()
         {
@@ -892,9 +897,9 @@ function Buffer() //{{{
         },
 
         /**
-         * The current browser's text zoom level, as a percentage with
+         * @property {number} The current browser's text zoom level, as a
-         * 100 as 'normal'. Affects text size, as well as image size
+         *     percentage with 100 as 'normal'. Affects text size, as well as
-         * and block size.
+         *     image size and block size.
          */
         get fullZoom()
         {
@@ -906,7 +911,7 @@ function Buffer() //{{{
         },
 
         /**
-         * The current document's title.
+         * @property {string} The current document's title.
          */
         get title()
         {
@@ -914,6 +919,7 @@ function Buffer() //{{{
         },
 
         /**
+         * Adds a new section to the page information output.
          *
          * @param {string} option The section's value in 'pageinfo'.
          * @param {string} title The heading for this section's
@@ -968,6 +974,8 @@ function Buffer() //{{{
          * positioned in.
          *
          * NOTE: might change the selection
+         *
+         * @returns {string}
          */
         // FIXME: getSelection() doesn't always preserve line endings, see:
         // https://www.mozdev.org/bugs/show_bug.cgi?id=19303
@@ -1022,9 +1030,8 @@ function Buffer() //{{{
         },
 
         /**
-         * Try to guess links the like of "next" and "prev". Though it
+         * Tries to guess links the like of "next" and "prev". Though it has a
-         * has a singularly horrendous name, it turns out to be quite
+         * singularly horrendous name, it turns out to be quite useful.
-         * useful.
          *
          * @param {string} rel The relationship to look for. Looks for
          *     links with matching @rel or @rev attributes, and,
@@ -1143,13 +1150,19 @@ function Buffer() //{{{
         },
 
         /**
-         * The current document's selection controller.
+         * @property {Object} The current document's selection controller.
          */
         get selectionController() getBrowser().docShell
                 .QueryInterface(Ci.nsIInterfaceRequestor)
                 .getInterface(Ci.nsISelectionDisplay)
                 .QueryInterface(Ci.nsISelectionController),
 
+        /**
+         * Saves a page link to disk.
+         *
+         * @param {Object} elem The page link to save.
+         * @param {boolean} skipPrompt Whether to open the "Save Link As..." dialog
+         */
         saveLink: function (elem, skipPrompt)
         {
             let doc  = elem.ownerDocument;
@@ -1225,7 +1238,13 @@ function Buffer() //{{{
             win.scrollByPages(pages);
         },
 
-        scrollByScrollSize: function (count, direction)
+        /**
+         * Scrolls the buffer vertically <b>count</b> * 'scroll' rows.
+         *
+         * @param {number} count The multiple of 'scroll' lines to scroll.
+         * @param {number} direction The direction to scroll, down if 1 and up if -1.
+         */
+        scrollByScrollSize: function (count, direction) // XXX: boolean
         {
             if (count > 0)
                 options["scroll"] = count;
@@ -1240,7 +1259,9 @@ function Buffer() //{{{
         },
 
         /**
-         * Scrolls the current buffer vertically to <b>percentage</b>
+         * Scrolls the current buffer vertically to <b>percentage</b>.
+         *
+         * @param {number} percentage The page percentile to scroll the buffer to.
          */
         scrollToPercentile: function (percentage)
         {
@@ -1264,6 +1285,13 @@ function Buffer() //{{{
         },
 
         // TODO: allow callback for filtering out unwanted frames? User defined?
+        /**
+         * Shifts the focus to another frame within the buffer. Each buffer
+         * contains at least one frame.
+         *
+         * @param {number} count The number of frames to skip through.
+         * @param {boolean} forward The direction of motion.
+         */
         shiftFrameFocus: function (count, forward)
         {
             if (!window.content.document instanceof HTMLDocument)
@@ -1342,11 +1370,23 @@ function Buffer() //{{{
 
         // similar to pageInfo
         // TODO: print more useful information, just like the DOM inspector
+        /**
+         * Displays information about the specified element.
+         *
+         * @param {Object} elem
+         */
         showElementInfo: function (elem)
         {
             liberator.echo(<>Element:<br/>{util.objectToString(elem, true)}</>, commandline.FORCE_MULTILINE);
         },
 
+        /**
+         * Displays information about the current buffer.
+         *
+         * @param {boolean} verbose Display more verbose information.
+         * @param {string} sections A string limiting the displayed sections.
+         * @default The value of 'pageinfo'.
+         */
         showPageInfo: function (verbose, sections)
         {
             // Ctrl-g single line output
@@ -1376,6 +1416,9 @@ function Buffer() //{{{
             liberator.echo(list, commandline.FORCE_MULTILINE);
         },
 
+        /**
+         * Opens a viewer to inspect the source of the currently selected range.
+         */
         viewSelectionSource: function ()
         {
             // copied (and tuned somebit) from browser.jar -> nsContextMenu.js
@@ -1396,6 +1439,15 @@ function Buffer() //{{{
                     docUrl, docCharset, reference, "selection");
         },
 
+        /**
+         * Opens a viewer to inspect the source of the current buffer or the
+         * specified <b>url</b>. Either the default viewer or the configured
+         * external editor is used.
+         *
+         * @param {string} url The URL of the source.
+         * @default The current buffer.
+         * @param {boolean} useExternalEditor View the source in the external editor.
+         */
         viewSource: function (url, useExternalEditor)
         {
             url = url || buffer.URL;
@@ -1406,11 +1458,23 @@ function Buffer() //{{{
                 liberator.open("view-source:" + url);
         },
 
+        /**
+         * Increases the zoom level of the current buffer.
+         *
+         * @param {number} steps The number of zoom levels to jump.
+         * @param {boolean} fullZoom Whether to use full zoom or text zoom.
+         */
         zoomIn: function (steps, fullZoom)
         {
             bumpZoomLevel(steps, fullZoom);
         },
 
+        /**
+         * Decreases the zoom level of the current buffer.
+         *
+         * @param {number} steps The number of zoom levels to jump.
+         * @param {boolean} fullZoom Whether to use full zoom or text zoom.
+         */
         zoomOut: function (steps, fullZoom)
         {
             bumpZoomLevel(-steps, fullZoom);

common/content/commands.js

@@ -29,7 +29,7 @@ the terms of any one of the MPL, the GPL or the LGPL.
 /** @scope modules */
 
 /**
- * A class representing EX commands. Instances are created by
+ * A class representing Ex commands. Instances are created by
  * the {@link Commands} class.
  *
  * @private
@@ -86,7 +86,7 @@ function Command(specs, description, action, extraInfo) //{{{
     /** @property {string[]} All of this command's long names, e.g., "command" */
     this.longNames  = expandedSpecs.longNames;
 
-    /** @property {string} The command's cannonical name. */
+    /** @property {string} The command's canonical 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
@@ -189,6 +189,7 @@ Command.prototype = {
      * Returns whether this command may be invoked via <b>name</b>.
      *
      * @param {string} name
+     * @returns {boolean}
      */
     hasName: function (name)
     {
@@ -214,7 +215,7 @@ Command.prototype = {
      *     purposes.
      * @param {Object} extra Extra keys to be spliced into the
      *     returned Args object.
-     * @returns Args
+     * @returns {Args}
      * @see Commands#parseArgs
      */
     parseArgs: function (args, complete, extra) commands.parseArgs(args, this.options, this.argCount, false, this.literal, complete, extra)
@@ -769,7 +770,7 @@ function Commands() //{{{
         {
             return str.replace(/<((?:q-)?)([a-zA-Z]+)?>/g, function (match, quote, token)
             {
-                if (token == "lt") // Don't quote, as in vim (but, why so in vim? You'd think people wouldn't say <q-lt> if they didn't want it)
+                if (token == "lt") // Don't quote, as in Vim (but, why so in Vim? You'd think people wouldn't say <q-lt> if they didn't want it)
                     return "<";
                 let res = tokens[token];
                 if (res == undefined) // Ignore anything undefined

common/content/completion.js

@@ -66,7 +66,8 @@ function CompletionContext(editor, name, offset) //{{{
             self.contexts[name] = this;
 
         /**
-         * @property {CompletionContext} This context's parent. {null} when this is a top-level context.
+         * @property {CompletionContext} This context's parent. {null} when
+         *     this is a top-level context.
          */
         self.parent = parent;
 
@@ -82,7 +83,7 @@ function CompletionContext(editor, name, offset) //{{{
 
         /**
          * @property {boolean} Specifies that this context is not finished
-         *      generating results.
+         *     generating results.
          * @default false
          */
         self.incomplete = false;
@@ -141,7 +142,7 @@ function CompletionContext(editor, name, offset) //{{{
         }];
         /**
          * @property {boolean} Specifies whether this context results must
-         *     match the filter at the begining of the string.
+         *     match the filter at the beginning of the string.
          * @default true
          */
         this.anchored = true;
@@ -159,7 +160,7 @@ function CompletionContext(editor, name, offset) //{{{
          */
         this.keys = { text: 0, description: 1, icon: "icon" };
         /**
-         * @property {number} This context's offset from the begining of
+         * @property {number} This context's offset from the beginning of
          *     {@link #editor}'s value.
          */
         this.offset = offset || 0;
@@ -653,7 +654,7 @@ CompletionContext.prototype = {
     /**
      * Wait for all subcontexts to complete.
      *
-     * @param {boolean} interruptable When true, the call may be interrupted
+     * @param {boolean} interruptible When true, the call may be interrupted
      *    via <C-c>. In this case, "Interrupted" may be thrown.
      * @param {number} timeout The maximum time, in milliseconds, to wait.
      */
@@ -1073,7 +1074,7 @@ function Completion() //{{{
                     compl = function (context, obj)
                     {
                         context.process = [null, function highlight(item, v) template.highlight(v, true)];
-                        // Sort in a logical fasion for object keys:
+                        // Sort in a logical fashion for object keys:
                         //  Numbers are sorted as numbers, rather than strings, and appear first.
                         //  Constants are unsorted, and appear before other non-null strings.
                         //  Other strings are sorted in the default manner.
@@ -1142,12 +1143,12 @@ function Completion() //{{{
                      *  [-3]: base statement
                      */
 
-                    // Yes. If the [ starts at the begining of a logical
+                    // Yes. If the [ starts at the beginning of a logical
                     // statement, we're in an array literal, and we're done.
                      if (get(-3, 0, STATEMENTS) == get(-2)[OFFSET])
                         return;
 
-                    // Begining of the statement upto the opening [
+                    // Beginning of the statement upto the opening [
                     let obj = getObj(-3, get(-2)[OFFSET]);
 
                     return complete.call(this, obj, getKey(), null, string, last);
@@ -1628,9 +1629,8 @@ function Completion() //{{{
             let completions = completer(context);
             if (!completions)
                 return;
-            /* Not vim compatible, but is a significant enough improvement
+            // Not Vim compatible, but is a significant enough improvement
-             * that it's worth breaking compatibility.
+            // that it's worth breaking compatibility.
-             */
             if (newValues instanceof Array)
             {
                 completions = completions.filter(function (val) newValues.indexOf(val[0]) == -1);

common/content/editor.js

@@ -709,7 +709,7 @@ function Editor() //{{{
 
         // This function will move/select up to given "pos"
         // Simple setSelectionRange() would be better, but we want to maintain the correct
-        // order of selectionStart/End (a firefox bug always makes selectionStart <= selectionEnd)
+        // order of selectionStart/End (a Firefox bug always makes selectionStart <= selectionEnd)
         // Use only for small movements!
         moveToPosition: function (pos, forward, select)
         {
@@ -900,7 +900,7 @@ function Editor() //{{{
         //
         // if filter == ! remove all and add it as only END
         //
-        // variant 1: rhs matches anywere in loop
+        // variant 1: rhs matches anywhere in loop
         //
         //          1 mod matches anywhere in loop
         //                  a) simple replace and
@@ -913,7 +913,7 @@ function Editor() //{{{
         //                 (b) a ! is there. do nothing END)
         //
         // variant 2: rhs matches *no*were in loop and filter is c or i
-        //            everykind of current combo is possible to 1 {c,i,!} or two {c and i}
+        //            every kind of current combo is possible to 1 {c,i,!} or two {c and i}
         //
         //          1 mod is ! split into two i + c END
         //          1 not !: opposite mode (first), add/change 'second' and END

common/content/events.js

@@ -528,7 +528,7 @@ function Events() //{{{
             {
                 // hacky way to get rid of "Transfering data from ..." on sites with frames
                 // when you click on a link inside a frameset, because asyncUpdateUI
-                // is not triggered there (firefox bug?)
+                // is not triggered there (Firefox bug?)
                 setTimeout(statusline.updateUrl, 10);
                 return;
             }
@@ -836,7 +836,7 @@ function Events() //{{{
         },
 
         // This method pushes keys into the event queue from liberator
-        // it is similar to vim's feedkeys() method, but cannot cope with
+        // it is similar to 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
@@ -1081,10 +1081,10 @@ function Events() //{{{
             return ret;
         },
 
-        // argument "event" is delibarately not used, as i don't seem to have
+        // argument "event" is deliberately not used, as i don't seem to have
         // access to the real focus target
         //
-        // the ugly wantsModeReset is needed, because firefox generates a massive
+        // the ugly wantsModeReset is needed, because Firefox generates a massive
         // amount of focus changes for things like <C-v><C-k> (focusing the search field)
         onFocusChange: function (event)
         {
@@ -1131,7 +1131,7 @@ function Events() //{{{
 
                 if (config.name == "Muttator")
                 {
-                    // we switch to -- MESSAGE -- mode for muttator, when the main HTML widget gets focus
+                    // we switch to -- MESSAGE -- mode for Muttator, when the main HTML widget gets focus
                     if (hasHTMLDocument(win) || elem instanceof HTMLAnchorElement)
                     {
                         if (config.isComposeWindow)
@@ -1337,7 +1337,7 @@ function Events() //{{{
                 return false;
             }
 
-            // XXX: ugly hack for now pass certain keys to firefox as they are without beeping
+            // XXX: ugly hack for now pass certain keys to Firefox as they are without beeping
             // also fixes key navigation in combo boxes, submitting forms, etc.
             // FIXME: breaks iabbr for now --mst
             if ((config.name == "Vimperator" && liberator.mode == modes.NORMAL)
@@ -1376,7 +1376,7 @@ function Events() //{{{
                         return false;
                     }
 
-                    // others are left to generate the 'input' event or handled by firefox
+                    // others are left to generate the 'input' event or handled by Firefox
                     return;
                 }
             }
@@ -1506,7 +1506,7 @@ function Events() //{{{
 
                 if (key != "<Esc>" && key != "<C-[>")
                 {
-                    // allow key to be passed to firefox if we can't handle it
+                    // allow key to be passed to Firefox if we can't handle it
                     stop = false;
 
                     if (liberator.mode == modes.COMMAND_LINE)

common/content/find.js

@@ -108,7 +108,7 @@ function Search() //{{{
         // strip case-sensitive modifiers
         pattern = pattern.replace(/(\\)?\\[cC]/g, function ($0, $1) { return $1 ? $0 : ""; });
 
-        // remove any modifer escape \
+        // remove any modifier escape \
         pattern = pattern.replace(/\\(\\[cClL])/g, "$1");
 
         searchString = pattern;
@@ -440,7 +440,7 @@ function Search() //{{{
             // TODO: code to reposition the document to the place before search started
         },
 
-        // FIXME: thunderbird incompatible
+        // FIXME: Thunderbird incompatible
         // this is not dependent on the value of 'hlsearch'
         highlight: function (text)
         {

common/content/hints.js

@@ -47,7 +47,7 @@ function Hints() //{{{
     var hintNumber = 0;  // only the numerical part of the hint
     var usedTabKey = false; // when we used <Tab> to select an element
     var prevInput = "";    // record previous user input type, "text" || "number"
-    var extendedhintCount;  // for the count arugument of Mode#action (extended hint only)
+    var extendedhintCount;  // for the count argument of Mode#action (extended hint only)
 
     // hints[] = [elem, text, span, imgspan, elem.style.backgroundColor, elem.style.color]
     var pageHints = [];
@@ -340,7 +340,7 @@ function Hints() //{{{
         removeHints(timeout);
 
         if (timeout == 0)
-            // force a possible mode change, based on wheter an input field has focus
+            // force a possible mode change, based on whether an input field has focus
             events.onFocusChange();
         setTimeout(function () {
             if (modes.extended & modes.HINTS)

common/content/io.js

@@ -509,7 +509,7 @@ function IO() //{{{
             switch (EXTENSION_NAME)
             {
                 case "muttator":
-                    tmpName = "mutt-ator-mail"; // to allow vim to :set ft=mail automatically
+                    tmpName = "mutt-ator-mail"; // to allow Vim to :set ft=mail automatically
                     break;
                 case "vimperator":
                     try
@@ -629,7 +629,7 @@ function IO() //{{{
             else
             {
                 let dirs = services.get("environment").get("PATH").split(WINDOWS ? ";" : ":");
-                // Windows tries the cwd first TODO: desirable?
+                // Windows tries the CWD first TODO: desirable?
                 if (WINDOWS)
                     dirs = [io.getCurrentDirectory().path].concat(dirs);
 
@@ -748,7 +748,7 @@ lookup:
             return found;
         },
 
-        // files which end in .js are sourced as pure javascript files,
+        // files which end in .js are sourced as pure JavaScript files,
         // no need (actually forbidden) to add: js <<EOF ... EOF around those files
         source: function (filename, silent)
         {
@@ -781,7 +781,7 @@ lookup:
                 let str = ioManager.readFile(file);
                 let uri = ioService.newFileURI(file);
 
-                // handle pure javascript files specially
+                // handle pure JavaScript files specially
                 if (/\.js$/.test(filename))
                 {
                     try

common/content/liberator.js

@@ -83,7 +83,7 @@ const liberator = (function () //{{{
         }
     }
 
-    // Only general options are added here, which are valid for all vimperator like extensions
+    // Only general options are added here, which are valid for all Vimperator like extensions
     registerObserver("load_options", function ()
     {
         options.add(["errorbells", "eb"],
@@ -364,7 +364,7 @@ const liberator = (function () //{{{
             "Run a JavaScript command through eval()",
             function (args)
             {
-                if (args.bang) // open javascript console
+                if (args.bang) // open JavaScript console
                 {
                     liberator.open("chrome://global/content/console.xul",
                         (options["newtab"] && options.get("newtab").has("all", "javascript"))
@@ -1034,7 +1034,7 @@ const liberator = (function () //{{{
             });
         },
 
-        // logs a message to the javascript error console
+        // logs a message to the JavaScript error console
         // if msg is an object, it is beautified
         // TODO: add proper level constants
         log: function (msg, level)

common/content/mappings.js

@@ -283,7 +283,7 @@ function Mappings() //{{{
 
     // FIXME:
     Mappings.flags = {
-        ALLOW_EVENT_ROUTING: 1 << 0, // if set, return true inside the map command to pass the event further to firefox
+        ALLOW_EVENT_ROUTING: 1 << 0, // if set, return true inside the map command to pass the event further to Firefox
         MOTION:              1 << 1,
         COUNT:               1 << 2,
         ARGUMENT:            1 << 3

common/content/options.js

@@ -578,10 +578,10 @@ function Options() //{{{
     }
 
     //
-    // firefox preferences which need to be changed to work well with vimperator
+    // Firefox preferences which need to be changed to work well with Vimperator
     //
 
-    // work around firefox popup blocker
+    // work around Firefox popup blocker
     // TODO: Make this work like safeSetPref
     var popupAllowedEvents = loadPreference("dom.popup_allowed_events", "change click dblclick mouseup reset submit");
     if (!/keypress/.test(popupAllowedEvents))
@@ -601,7 +601,7 @@ function Options() //{{{
         // TODO: move to buffer.js
         // we have our own typeahead find implementation
         options.safeSetPref("accessibility.typeaheadfind.autostart", false);
-        options.safeSetPref("accessibility.typeaheadfind", false); // actually the above setting should do it, but has no effect in firefox
+        options.safeSetPref("accessibility.typeaheadfind", false); // actually the above setting should do it, but has no effect in Firefox
     });
 
     // start with saved session

common/content/style.js

@@ -129,7 +129,7 @@ Highlights.prototype.CSS = <![CDATA[
 
 /**
  * A class to manage highlighting rules. The parameters are the
- * standard paramaters for any {@link Storage} object.
+ * standard parameters for any {@link Storage} object.
  *
  * @author Kris Maglione <maglione.k@gmail.com>
  */
@@ -192,6 +192,8 @@ function Highlights(name, store, serial)
 
     /**
      * Gets a CSS selector given a highlight group.
+     *
+     * @param {string} class
      */
     this.selector = function (class)
     {
@@ -238,7 +240,7 @@ function Highlights(name, store, serial)
 /**
  * Manages named and unnamed user stylesheets, which apply to both
  * chrome and content pages. The parameters are the standard
- * paramaters for any {@link Storage} object.
+ * parameters for any {@link Storage} object.
  *
  * @author Kris Maglione <maglione.k@gmail.com>
  */
@@ -337,6 +339,12 @@ function Styles(name, store, serial)
     /**
      * Find sheets matching the parameters. See {@link #addSheet}
      * for parameters.
+     *
+     * @param {boolean} system
+     * @param {string} name
+     * @param {string} filter
+     * @param {string} css
+     * @param {number} index
      */
     this.findSheets = function (system, name, filter, css, index)
     {
@@ -361,6 +369,12 @@ function Styles(name, store, serial)
      * In cases where <b>filter</b> is supplied, the given filters
      * are removed from matching sheets. If any remain, the sheet is
      * left in place.
+     *
+     * @param {boolean} system
+     * @param {string} name
+     * @param {string} filter
+     * @param {string} css
+     * @param {number} index
      */
     this.removeSheet = function (system, name, filter, css, index)
     {
@@ -407,7 +421,7 @@ function Styles(name, store, serial)
     /**
      * Register a user stylesheet at the given URI.
      *
-     * @param {string} uri The UrI of the sheet to register.
+     * @param {string} uri The URI of the sheet to register.
      * @param {boolean} reload Whether to reload any sheets that are
      *     already registered.
      */
@@ -422,6 +436,8 @@ function Styles(name, store, serial)
 
     /**
      * Unregister a sheet at the given URI.
+     *
+     * @param {string} uri The URI of the sheet to unregister.
      */
     this.unregisterSheet = function (uri)
     {
@@ -433,6 +449,8 @@ function Styles(name, store, serial)
     // FIXME
     /**
      * Register an agent stylesheet.
+     *
+     * @param {string} uri The URI of the sheet to register.
      * @deprecated
      */
     this.registerAgentSheet = function (uri)
@@ -444,6 +462,8 @@ function Styles(name, store, serial)
 
     /**
      * Unregister an agent stylesheet.
+     *
+     * @param {string} uri The URI of the sheet to unregister.
      * @deprecated
      */
     this.unregisterAgentSheet = function (uri)
@@ -516,7 +536,6 @@ liberator.registerObserver("load_completion", function ()
 
 liberator.registerObserver("load_commands", function ()
 {
-    // TODO: :colo default needs :hi clear
     commands.add(["colo[rscheme]"],
         "Load a color scheme",
         function (args)

common/content/ui.js

@@ -925,7 +925,7 @@ function CommandLine() //{{{
             liberator.triggerCallback("change", currentExtendedMode, cmd);
         },
 
-        // normally used when pressing esc, does not execute a command
+        // normally used when pressing <Esc>, does not execute a command
         close: function close()
         {
             let mode = currentExtendedMode;
@@ -963,7 +963,7 @@ function CommandLine() //{{{
             commandlineWidget.collapsed = true;
         },
 
-        // liberator.echo uses different order of flags as it omits the hightlight group, change v.commandline.echo argument order? --mst
+        // liberator.echo uses different order of flags as it omits the highlight group, change v.commandline.echo argument order? --mst
         echo: function echo(str, highlightGroup, flags)
         {
             if (silent)
@@ -1287,7 +1287,7 @@ function CommandLine() //{{{
                     }
                     break;
 
-                // let firefox handle those to select table cells or show a context menu
+                // let Firefox handle those to select table cells or show a context menu
                 case "<C-LeftMouse>":
                 case "<RightMouse>":
                 case "<C-S-LeftMouse>":
@@ -1446,9 +1446,9 @@ function CommandLine() //{{{
 /**
  * The list which is used for the completion box (and QuickFix window in future)
  *
- * @param id: the id of the the XUL <iframe> which we want to fill
+ * @param {string} id The id of the XUL <iframe> which we want to fill it
- *            it MUST be inside a <vbox> (or any other html element,
+ *     MUST be inside a <vbox> (or any other html element, because otherwise
- *            because otherwise setting the height does not work properly
+ *     setting the height does not work properly
  */
 function ItemList(id) //{{{
 {
@@ -1539,10 +1539,10 @@ function ItemList(id) //{{{
     }
 
     /**
-     * uses the entries in "items" to fill the listbox
+     * Uses the entries in "items" to fill the listbox and
-     * does incremental filling to speed up things
+     * does incremental filling to speed up things.
      *
-     * @param offset: start at this index and show maxItems
+     * @param {number} offset Start at this index and show maxItems
      */
     function fill(offset)
     {
@@ -1660,7 +1660,7 @@ function ItemList(id) //{{{
         // select index, refill list if necessary
         selectItem: function selectItem(index)
         {
-            //if (container.collapsed) // fixme
+            //if (container.collapsed) // FIXME
             //    return;
 
             //let now = Date.now();
@@ -1783,7 +1783,7 @@ function StatusLine() //{{{
             this.updateBufferPosition();
         },
 
-        // if "url" is ommited, build a usable string for the URL
+        // if "url" is omitted, build a usable string for the URL
         updateUrl: function updateUrl(url)
         {
             if (typeof url == "string")
@@ -1794,7 +1794,7 @@ function StatusLine() //{{{
 
             url = buffer.URL;
 
-            // make it even more vim-like
+            // make it even more Vim-like
             if (url == "about:blank")
             {
                 if (!buffer.title)

common/content/util.js

@@ -57,15 +57,19 @@ const util = { //{{{
         },
 
         /**
-         * Flatten an array, such that all elements of the array are
+         * Flattens an array, such that all elements of the array are
          * joined into a single array:
          *    [["foo", ["bar"]], ["baz"], "quux"] -> ["foo", ["bar"], "baz", "quux"]
+         *
+         * @param {Array} ary
+         * @returns {Array}
          */
         flatten: function flatten(ary) Array.concat.apply([], ary),
 
         /**
          * Returns an Iterator for an array's values.
          *
+         * @param {Array} ary
          * @returns {Iterator(Object)}
          */
         iterator: function iterator(ary)
@@ -76,8 +80,9 @@ const util = { //{{{
         },
 
         /**
-         * Returns an Iterator for the arrays indices and values.
+         * Returns an Iterator for an array's indices and values.
          *
+         * @param {Array} ary
          * @returns {Iterator([{number}, {Object}])}
          */
         iterator2: function (ary)
@@ -94,6 +99,7 @@ const util = { //{{{
          *
          * @param {Array} ary
          * @param {boolean} unsorted
+         * @returns {Array}
          */
         uniq: function uniq(ary, unsorted)
         {
@@ -135,10 +141,10 @@ const util = { //{{{
 
     /**
      * Clips a string to a given length. If the input string is longer
-     * than <b>length</b>, an elipsis is appended.
+     * than <b>length</b>, an ellipsis is appended.
      *
-     * @param {string} str
+     * @param {string} str The string to truncate.
-     * @param {number} length
+     * @param {number} length The length of the returned string.
      * @returns {string}
      */
     clip: function clip(str, length)
@@ -169,6 +175,13 @@ const util = { //{{{
         return node.ownerDocument.defaultView.getComputedStyle(node, null);
     },
 
+    /**
+     * Copies a string to the system clipboard. If <b>verbose</b> is specified
+     * the copied string is also echoed to the command-line.
+     *
+     * @param {string} str
+     * @param {boolean} verbose
+     */
     copyToClipboard: function copyToClipboard(str, verbose)
     {
         const clipboardHelper = Cc["@mozilla.org/widget/clipboardhelper;1"].getService(Ci.nsIClipboardHelper);
@@ -178,12 +191,26 @@ const util = { //{{{
             liberator.echo("Yanked " + str, commandline.FORCE_SINGLELINE);
     },
 
+    /**
+     * Converts any arbitrary string into an URI object.
+     *
+     * @param {string} str
+     * @returns {Object}
+     */
+    // FIXME: newURI needed too?
     createURI: function createURI(str)
     {
         const fixup = Cc["@mozilla.org/docshell/urifixup;1"].getService(Ci.nsIURIFixup);
         return fixup.createFixupURI(str, fixup.FIXUP_FLAG_ALLOW_KEYWORD_LOOKUP);
     },
 
+    /**
+     * Converts HTML special characters in <b>str</b> to the equivalent HTML
+     * entities.
+     *
+     * @param {string} str
+     * @returns {string}
+     */
     escapeHTML: function escapeHTML(str)
     {
         // XXX: the following code is _much_ slower than a simple .replace()
@@ -195,11 +222,26 @@ const util = { //{{{
         return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
     },
 
+    /**
+     * Escapes Regular Expression special characters in <b>str</b>.
+     *
+     * @param {string} str
+     * @returns {string}
+     */
     escapeRegex: function escapeRegex(str)
     {
         return str.replace(/([\\{}()[\].?*+])/g, "\\$1");
     },
 
+    /**
+     * Escapes quotes, newline and tab characters in <b>str</b>. The returned
+     * string is delimited by <b>delimiter</b> or " if <b>delimiter</b> is not
+     * specified.
+     *
+     * @param {string} str
+     * @param {string} delimiter
+     * @returns {string}
+     */
     escapeString: function escapeString(str, delimiter)
     {
         if (delimiter == undefined)
@@ -207,11 +249,20 @@ const util = { //{{{
         return delimiter + str.replace(/([\\'"])/g, "\\$1").replace("\n", "\\n", "g").replace("\t", "\\t", "g") + delimiter;
     },
 
-    formatBytes: function formatBytes(num, decimalPlaces, humanReadable)
+    /**
+     * Converts <b>bytes</b> to a pretty printed data size string.
+     *
+     * @param {number} bytes The number of bytes.
+     * @param {string} decimalPlaces The number of decimal places to use if
+     *     <b>humanReadable</b> is true.
+     * @param {boolean} humanReadable Use byte multiples.
+     * @returns {string}
+     */
+    formatBytes: function formatBytes(bytes, decimalPlaces, humanReadable)
     {
         const unitVal = ["Bytes", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB"];
         let unitIndex = 0;
-        let tmpNum = parseInt(num, 10) || 0;
+        let tmpNum = parseInt(bytes, 10) || 0;
         let strNum = [tmpNum + ""];
 
         if (humanReadable)
@@ -242,33 +293,40 @@ const util = { //{{{
         return strNum[0] + " " + unitVal[unitIndex];
     },
 
-    // generates an Asciidoc help entry, "command" can also be a mapping
+    /**
-    generateHelp: function generateHelp(command, extraHelp)
+     * Generates an Asciidoc help entry.
+     *
+     * @param {Object} obj A liberator <b>Command</b>, <b>Mapping</b> or
+     *     <b>Option</b> object
+     * @param {string} extraHelp Extra help text beyond the description.
+     * @returns {string}
+     */
+    generateHelp: function generateHelp(obj, extraHelp)
     {
         let start = "", end = "";
-        if (command instanceof liberator.Command)
+        if (obj instanceof Command)
             start = ":";
-        else if (command instanceof liberator.Option)
+        else if (obj instanceof Option)
             start = end = "'";
 
         let ret = "";
         let longHelp = false;
-        if ((command.help && command.description) && (command.help.length + command.description.length) > 50)
+        if ((obj.help && obj.description) && (obj.help.length + obj.description.length) > 50)
             longHelp = true;
 
         // the tags which are printed on the top right
-        for (let j = command.names.length - 1; j >= 0; j--)
+        for (let j = obj.names.length - 1; j >= 0; j--)
-            ret += "|" + start + command.names[j] + end + "| ";
+            ret += "|" + start + obj.names[j] + end + "| ";
 
         if (longHelp)
             ret += "+";
 
         ret += "\n";
 
-        // the usage information for the command
+        // the usage information
-        let usage = command.names[0];
+        let usage = obj.names[0];
-        if (command.specs) // for :commands
+        if (obj.specs) // for :commands
-            usage = command.specs[0];
+            usage = obj.specs[0];
 
         usage = usage.replace(/{/, "\\\\{").replace(/}/, "\\\\}");
         usage = usage.replace(/'/, "\\'").replace(/`/, "\\`");
@@ -279,9 +337,9 @@ const util = { //{{{
         ret += "\n________________________________________________________________________________\n";
 
         // the actual help text
-        if (command.description)
+        if (obj.description)
         {
-            ret += command.description + "."; // the help description
+            ret += obj.description + "."; // the help description
             if (extraHelp)
                 ret += " +\n" + extraHelp;
         }
@@ -294,6 +352,16 @@ const util = { //{{{
         return ret;
     },
 
+    /**
+     * Sends a synchronous HTTP request to <b>url</b> and returns the
+     * XMLHttpRequest object. If <b>callback</b> is specified the request is
+     * asynchronous and the <b>callback</b> is invoked with the object as its
+     * argument.
+     *
+     * @param {string} url
+     * @param {function} callback
+     * @returns {Object}
+     */
     httpGet: function httpGet(url, callback)
     {
         try
@@ -317,8 +385,21 @@ const util = { //{{{
         }
     },
 
+    /**
+     * The identity function.
+     *
+     * @param {Object} k
+     * @returns {Object}
+     */
     identity: function identity(k) k,
 
+    /**
+     * Returns the intersection of two rectangles.
+     *
+     * @param {Object} r1
+     * @param {Object} r2
+     * @returns {Object}
+     */
     intersection: function (r1, r2) ({
         get width()  this.right - this.left,
         get height() this.bottom - this.top,
@@ -328,6 +409,14 @@ const util = { //{{{
         bottom: Math.min(r1.bottom, r2.bottom)
     }),
 
+    /**
+     * Returns the array that results from applying <b>fn</b> to each property
+     * of <b>obj</b>.
+     *
+     * @param {Object} obj
+     * @param {function} fn
+     * @returns {Array}
+     */
     map: function map(obj, fn)
     {
         let ary = [];
@@ -336,20 +425,33 @@ const util = { //{{{
         return ary;
     },
 
-    newURI: function (url)
+    /**
+     * Converts a URI string into an URI object.
+     *
+     * @param {string} uri
+     * @returns {Object}
+     */
+    // FIXME: createURI needed too?
+    newURI: function (uri)
     {
         const ioService = Cc["@mozilla.org/network/io-service;1"].getService(Ci.nsIIOService);
-        return ioService.newURI(url, null, null);
+        return ioService.newURI(uri, null, null);
     },
 
-    // if color = true it uses HTML markup to color certain items
+    /**
+     * Pretty print a JavaScript object. Use HTML markup to color certain items
+     * if <b>color</b> is true.
+     *
+     * @param {Object} object The object to pretty print.
+     * @param {boolean} color Whether the output should be colored.
+     * @returns {string}
+     */
     objectToString: function objectToString(object, color)
     {
-        /* Use E4X literals so html is automatically quoted
+        // Use E4X literals so html is automatically quoted
-         * only when it's asked for. Noone wants to see &lt;
+        // only when it's asked for. Noone wants to see &lt;
-         * on their console or :map :foo in their buffer
+        // on their console or :map :foo in their buffer
-         * when they expect :map <C-f> :foo.
+        // when they expect :map <C-f> :foo.
-         */
         XML.prettyPrinting = false;
         XML.ignoreWhitespace = false;
 
@@ -417,6 +519,15 @@ const util = { //{{{
         return color ? string : [s for each (s in string)].join("");
     },
 
+    /**
+     * A generator that returns the values between <b>start</b> and <b>end</b>.
+     * If <b>reverse</b> is true then the values are returned in reverse order.
+     *
+     * @param {number} start The interval's start value.
+     * @param {number} end The interval's end value.
+     * @param {boolean} reverse Reverse the order in which the values are produced.
+     * @returns {Iterator(Object)}
+     */
     range: function range(start, end, reverse)
     {
         if (!reverse)
@@ -431,6 +542,15 @@ const util = { //{{{
         }
     },
 
+    /**
+     * An interruptible generator that returns all values between <b>start</b>
+     * and <b>end</b>. The thread yields every <b>time</b> milliseconds.
+     *
+     * @param {number} start The interval's start value.
+     * @param {number} end The interval's end value.
+     * @param {number} time The time in milliseconds between thread yields.
+     * @returns {Iterator(Object)}
+     */
     interruptableRange: function interruptableRange(start, end, time)
     {
         let endTime = Date.now() + time;
@@ -445,7 +565,14 @@ const util = { //{{{
         }
     },
 
-    // same as Firefox's readFromClipboard function, but needed for apps like Thunderbird
+    /**
+     * Reads a string from the system clipboard.
+     *
+     * This is same as Firefox's readFromClipboard function, but is needed for
+     * apps like Thunderbird which do not provide it.
+     *
+     * @returns {string}
+     */
     readFromClipboard: function readFromClipboard()
     {
         let url;
@@ -478,8 +605,15 @@ const util = { //{{{
         return url;
     },
 
-    // takes a string like 'google bla, www.osnews.com'
+    /**
-    // and returns an array ['www.google.com/search?q=bla', 'www.osnews.com']
+     * Returns an array of URLs parsed from <b>str</b>.
+     *
+     * Given a string like 'google bla, www.osnews.com' return an array
+     * ['www.google.com/search?q=bla', 'www.osnews.com']
+     *
+     * @param {string} str
+     * @returns {Array}
+     */
     stringToURLArray: function stringToURLArray(str)
     {
         let urls = str.split(RegExp("\s*" + options["urlseparator"] + "\s*"));
@@ -525,6 +659,14 @@ const util = { //{{{
         });
     },
 
+    /**
+     * Converts an E4X XML literal to a DOM node.
+     *
+     * @param {Node} node
+     * @param {Document} doc
+     * @param {Object} nodes
+     * @returns {Node}
+     */
     xmlToDom: function xmlToDom(node, doc, nodes)
     {
         XML.prettyPrinting = false;

muttator/content/config.js

@@ -31,7 +31,7 @@ const config = { //{{{
     name: "Muttator",
     hostApplication: "Thunderbird", // TODO: can this be found out otherwise? gBrandBundle.getString("brandShortName");
 
-    /*** optional options, there are checked for existance and a fallback provided  ***/
+    /*** optional options, there are checked for existence and a fallback provided  ***/
     features: ["hints", "mail", "marks", "addressbook", "tabs"],
     defaults: { guioptions: "frb" },
 

vimperator/content/bookmarks.js

@@ -61,7 +61,7 @@ function Bookmarks() //{{{
     const taggingService   = PlacesUtils.tagging;
     const faviconService   = Cc["@mozilla.org/browser/favicon-service;1"].getService(Ci.nsIFaviconService);
 
-    // XXX for strange firefox bug :(
+    // XXX for strange Firefox bug :(
     // Error: [Exception... "Component returned failure code: 0x8000ffff (NS_ERROR_UNEXPECTED) [nsIObserverService.addObserver]"
     //     nsresult: "0x8000ffff (NS_ERROR_UNEXPECTED)"
     //     location: "JS frame :: file://~firefox/components/nsTaggingService.js :: anonymous :: line 89"

vimperator/content/config.js

@@ -31,7 +31,7 @@ const config = { //{{{
     name: "Vimperator",
     hostApplication: "Firefox",
 
-    /*** optional options, there are checked for existance and a fallback provided  ***/
+    /*** optional options, there are checked for existence and a fallback provided  ***/
     features: ["bookmarks", "hints", "history", "marks", "quickmarks", "session", "tabs", "windows"],
     defaults: { guioptions: "rb" },
 

vimperator/regressions.js

@@ -64,7 +64,7 @@ let functions = [
 
 /////////////////////////////////////////////////////////////////////////////////////////
 // functions below should be as generic as possible, and not require being rewritten
-// even after doing major vimperator refactoring
+// even after doing major Vimperator refactoring
 /////////////////////////////////////////////////////////////////////////////////////////
 
 function resetEnvironment()