added comments to ui.js, thanks cirmin. Note: Please try

to avoid trailing whitespace, I had to remove 18 of these things, but
otherwise nice job, thanks :)

common/content/ui.js

@@ -75,6 +75,12 @@ function CommandLine() //{{{
     var keepCommand = false;
     var lastEcho = null;
 
+    /**
+     * A class for managing the history of an inputField
+     *
+     * @param {Object} inputField
+     * @param {string} mode
+     */
     function History(inputField, mode)
     {
         if (!(this instanceof arguments.callee))
@@ -85,11 +91,16 @@ function CommandLine() //{{{
         this.reset();
     }
     History.prototype = {
+        /**
+         * Empties the history.
+         */
         reset: function ()
         {
             this.index = null;
         },
-
+        /**
+         * Permanently save the history
+         */
         save: function ()
         {
             let str = this.input.value;
@@ -99,13 +110,23 @@ function CommandLine() //{{{
             this.store.push(str);
             this.store.truncate(options["history"], true);
         },
-
+        /**
+         * Set the current match to val
+         *
+         * @param {string} val
+         */
         replace: function (val)
         {
             this.input.value = val;
             liberator.triggerCallback("change", currentExtendedMode, val);
         },
 
+        /**
+         * move up or (if backward) down in the history
+         *
+         * @param {boolean} backward
+         * @param {boolean} matchCurrent XXX: what?
+         */
         select: function (backward, matchCurrent)
         {
             // always reset the tab completion if we use up/down keys
@@ -154,6 +175,11 @@ function CommandLine() //{{{
         }
     };
 
+    /**
+     * A class for tab completions on an input field
+     *
+     * @param {Object} input
+     */
     function Completions(input)
     {
         if (!(this instanceof arguments.callee))
@@ -529,16 +555,28 @@ function CommandLine() //{{{
     var multilineRegexp = null;
     var multilineCallback = null;
 
+    /**
+     * @private - highlight the messageBox according to group
+     */
     function setHighlightGroup(group)
     {
         messageBox.setAttributeNS(NS.uri, "highlight", group);
     }
 
-    // Whether the command line must be open.
+    /**
+     * @private - Determines whether the command line should be visible.
+     *
+     * @return {boolean}
+     */
     function commandShown() modes.main == modes.COMMAND_LINE &&
             !(modes.extended & (modes.INPUT_MULTILINE | modes.OUTPUT_MULTILINE));
 
-    // sets the prompt - for example, : or /
+    /**
+     * @private - set the prompt to val styled with highlightGroup
+     *
+     * @param {string} val
+     * @param {string} highlightGroup
+     */
     function setPrompt(val, highlightGroup)
     {
         promptWidget.value = val;
@@ -547,7 +585,11 @@ function CommandLine() //{{{
         promptWidget.setAttributeNS(NS.uri, "highlight", highlightGroup || commandline.HL_NORMAL);
     }
 
-    // sets the command - e.g. 'tabopen', 'open http://example.com/'
+    /**
+     * @private - set the command to cmd and move the user's cursor to the end.
+     *
+     * @param {string} cmd
+     */
     function setCommand(cmd)
     {
         commandWidget.value = cmd;
@@ -555,6 +597,14 @@ function CommandLine() //{{{
         commandWidget.selectionEnd = cmd.length;
     }
 
+    /**
+     * @private - display a message styled with highlightGroup
+     * and, if forceSingle is true, ensure it takes only one line.
+     *
+     * @param {string} str
+     * @param {string} highlightGroup
+     * @param {boolean} forceSingle
+     */
     function echoLine(str, highlightGroup, forceSingle)
     {
         setHighlightGroup(highlightGroup);
@@ -570,7 +620,14 @@ function CommandLine() //{{{
             echoMultiline(<span highlight="Message">{str}</span>, highlightGroup);
     }
 
-    // TODO: resize upon a window resize
+    /**
+     * Display a multiline message, possible through a "more" like interface
+     *
+     * TODO: resize upon a window resize
+     *
+     * @param {string} str
+     * @param {string} highlightGroup
+     */
     function echoMultiline(str, highlightGroup)
     {
         let doc = multilineOutputWidget.contentDocument;
@@ -615,6 +672,10 @@ function CommandLine() //{{{
         commandline.updateMorePrompt();
     }
 
+    /**
+     * @private - ensure that the Multiline input widget is the
+     * correct size.
+     */
     function autosizeMultilineInputWidget()
     {
         let lines = multilineInputWidget.value.split("\n").length - 1;
@@ -622,7 +683,16 @@ function CommandLine() //{{{
         multilineInputWidget.setAttribute("rows", Math.max(lines, 1));
     }
 
-    // used for the :echo[err] commands
+    /**
+     * @private - eval()s a javascript expression
+     * and returns a string suitable to be echo'd.
+     *
+     * If useColor is true, util.objectToString will
+     * colorize object output.
+     *
+     * @param {string} arg
+     * @param {boolean} useColor
+     */
     function echoArgumentToString(arg, useColor)
     {
         if (!arg)
@@ -891,6 +961,9 @@ function CommandLine() //{{{
                 storage.styles.removeSheet(true, "silent-mode");
         },
 
+        /**
+         * XXX: This function is not used!
+         */
         runSilently: function (fn, self)
         {
             let wasSilent = this.silent;
@@ -918,6 +991,16 @@ function CommandLine() //{{{
 
         get message() messageBox.value,
 
+        /**
+         * Changes the command line to display the following prompt (usually ":")
+         * followed by the command, in the given mode. Valid modes are
+         * attributes of the "modes" variable, and modes.EX is probably
+         * a good choice.
+         *
+         * @param {string} prompt
+         * @param {string} cmd
+         * @param {number} mode
+         */
         open: function open(prompt, cmd, extendedMode)
         {
             // save the current prompts, we need it later if the command widget
@@ -942,7 +1025,11 @@ function CommandLine() //{{{
             liberator.triggerCallback("change", currentExtendedMode, cmd);
         },
 
-        // normally used when pressing <Esc>, does not execute a command
+        /**
+         * Removes any input from the command line, without executing its
+         * contents. Removes any "More" windows or other such output.
+         * Pressing <ESC> in EX mode normally has this effect.
+         */
         close: function close()
         {
             let mode = currentExtendedMode;
@@ -976,14 +1063,33 @@ function CommandLine() //{{{
             keepCommand = false;
         },
 
+
+        /**
+         * Hide any auto-completion/More-ing that is happening.
+         */
         hide: function hide()
         {
             commandlineWidget.collapsed = true;
         },
 
-        // liberator.echo uses different order of flags as it omits the highlight group, change v.commandline.echo argument order? --mst
+        /**
+         * Output the given string onto the command line coloured
+         * using the rules according to highlightGroup. If not
+         * given higlightGroup defaults to commandline.HL_NORMAL
+         * and other possibe values are at commandline.HL_[A-Z]*.
+         *
+         * Flags can be any of:
+         *   commandline.APPEND_TO_MESSAGES (causes message to be added to the messagesHistory)
+         *   commandline.FORCE_SINGLELINE | commandline.DISALLOW_MULTILINE
+         *   commandline.FORCE_MULTILINE
+         *
+         * @param {string} str
+         * @param {string} highlightGroup
+         * @param {number} flags
+         */
         echo: function echo(str, highlightGroup, flags)
         {
+           // liberator.echo uses different order of flags as it omits the highlight group, change v.commandline.echo argument order? --mst
             if (silent)
                 return false;
 
@@ -1028,8 +1134,23 @@ function CommandLine() //{{{
             return true;
         },
 
-        // this will prompt the user for a string
+        /**
-        // commandline.input("(s)ave or (o)pen the file?")
+         * Prompt the user for a string and execute the given
+         * callback with that as the only argument on <CR>
+         * extra can have any of the following attributes:
+         *
+         *     onChange: A function to be called with the current input every time it changes
+         *     completer: A function called with a ?context? when the user tries to tabcomplete
+         *     promptHighlight: The HighlightGroup to use (default commandline.HL_QUESTION, others
+         *                      can be found at commandline.HL_[A-Z]*)
+         *
+         * This function sets the mode to modes.COMMAND_LINE, and thus popping the mode will
+         * stop further input from being waited for (useful for stopping onChange)
+         *
+         * @param {string} prompt
+         * @param {function(string)} callback
+         * @param {Object} extra
+         */
         input: function input(prompt, callback, extra)
         {
             extra = extra || {};
@@ -1049,8 +1170,14 @@ function CommandLine() //{{{
             completions = Completions(commandWidget.inputField);
         },
 
-        // reads a multi line input and returns the string once the last line matches
+        /**
-        // @param untilRegexp
+         * Get a multiline input from a user, up to but not including
+         * the line which matches the given regular expression. Then
+         * execute the callback with that string as a parameter.
+         *
+         * @param {RegExp} untilRegexp
+         * @param {function(string)} callbackFunc
+         */
         inputMultiline: function inputMultiline(untilRegexp, callbackFunc)
         {
             // Kludge.
@@ -1070,6 +1197,13 @@ function CommandLine() //{{{
             setTimeout(function () { multilineInputWidget.focus(); }, 10);
         },
 
+        /**
+         * Handle events, the come from liberator when liberator.mode = modes.COMMAND_LINE
+         * but also takes blur/focus/input events raw from #liberator-commandline-command
+         * in the XUL
+         *
+         * @param {Event} event
+         */
         onEvent: function onEvent(event)
         {
             let command = this.command;
@@ -1162,6 +1296,12 @@ function CommandLine() //{{{
             }
         },
 
+        /**
+         * Multiline input events, they will come straight from
+         * #liberator-multiline-input in the XUL.
+         *
+         * @param {Event} event
+         */
         onMultilineInputEvent: function onMultilineInputEvent(event)
         {
             if (event.type == "keypress")
@@ -1196,8 +1336,16 @@ function CommandLine() //{{{
             return true;
         },
 
-        // FIXME: if 'more' is set and the MOW is not scrollable we should still
+        /**
-        // allow a down motion after an up rather than closing
+         * Handle events when we are in multiline output mode,
+         * these come from liberator when modes.extended & modes.MULTILINE_OUTPUT
+         * and also from #liberator-multiline-output in the XUL
+         *
+         * FIXME: if 'more' is set and the MOW is not scrollable we should still
+         * allow a down motion after an up rather than closing
+         *
+         * @param {Event} event
+         */
         onMultilineOutputEvent: function onMultilineOutputEvent(event)
         {
             let win = multilineOutputWidget.contentWindow;
@@ -1407,6 +1555,15 @@ function CommandLine() //{{{
             }
         },
 
+        /**
+         * Refresh or remove the prompt that displays when in multiline mode.
+         * showHelp will cause the possible key-options to be displayed,
+         * force will cause a display of the default message even if it
+         * could be at the end of the output.
+         *
+         * @param {boolean} force
+         * @param {boolean} showHelp
+         */
         updateMorePrompt: function updateMorePrompt(force, showHelp)
         {
             if (outputContainer.collapsed)
@@ -1424,6 +1581,14 @@ function CommandLine() //{{{
                 echoLine("Press ENTER or type command to continue", this.HL_QUESTION, true);
         },
 
+        /**
+         * Changes the height of the multilineOutputWidget to fit
+         * its contents, if <b>open</b> is true, it will cause the
+         * widget to uncollapse, if not it will leave the widget
+         * closed.
+         *
+         * @param {boolean} open
+         */
         updateOutputHeight: function updateOutputHeight(open)
         {
             if (!open && outputContainer.collapsed)
@@ -1446,6 +1611,10 @@ function CommandLine() //{{{
             outputContainer.collapsed = false;
         },
 
+        /**
+         * Disable any active completion functions by calling their cancelFunc's
+         * Will also remove the completions preview window.
+         */
         resetCompletions: function resetCompletions()
         {
             autocompleteTimer.reset();
@@ -1782,6 +1951,14 @@ function StatusLine() //{{{
 
     return {
 
+        /**
+         * Update the status bar to indicate how secure the website is
+         * secure => https:// with valid certificate
+         * broken => https:// with invalid certificate
+         * insecure => http://
+         *
+         * @param {'secure'|'broken'|'insecure'} type
+         */
         setClass: function setClass(type)
         {
             const highlightGroup = {
@@ -1803,7 +1980,14 @@ function StatusLine() //{{{
             this.updateBufferPosition();
         },
 
-        // if "url" is omitted, build a usable string for the URL
+        /**
+         * Update which URL is displayed on the status line,
+         * if url is omitted then buffer.URL is used instead and
+         * status icons [+-❤] are updated to match whether one can
+         * go back/forwards in history/have bookmarked the page.
+         *
+         * @param {string} url
+         */
         updateUrl: function updateUrl(url)
         {
             if (typeof url == "string")
@@ -1846,6 +2030,13 @@ function StatusLine() //{{{
             urlWidget.value = url;
         },
 
+        /**
+         * Set the contents of the status line's input buffer
+         * to the given string.
+         *
+         * Used for displaying partial key combinations in
+         * normal mode.
+         */
         updateInputBuffer: function updateInputBuffer(buffer)
         {
             if (!buffer || typeof buffer != "string")
@@ -1854,6 +2045,17 @@ function StatusLine() //{{{
             inputBufferWidget.value = buffer;
         },
 
+        /**
+         * Update the display of the progress bar.
+         * If the parameter is a string, it will be
+         * displayed literally. Otherwise it must be a number
+         * less than one.
+         * Negative numbers cause a "Loading..." status,
+         * Positive (< 1) numbers cause an arrow ==> of length
+         * proportional to the arrow.
+         *
+         * @param {string|number} progress
+         */
         updateProgress: function updateProgress(progress)
         {
             if (!progress)
@@ -1881,7 +2083,13 @@ function StatusLine() //{{{
             }
         },
 
-        // you can omit either of the 2 arguments
+        /**
+         * Display the correct tabcount (e.g. [1/5]) on the status bar.
+         * If either parameter is omitted, they will be calculated.
+         *
+         * @param {number} currentIndex
+         * @param {number} totalTabs
+         */
         updateTabCount: function updateTabCount(currentIndex, totalTabs)
         {
             if (!liberator.has("tabs"))
@@ -1906,7 +2114,16 @@ function StatusLine() //{{{
             tabCountWidget.value = "[" + currentIndex + "/" + totalTabs + "]";
         },
 
-        // percent is given between 0 and 1
+        /**
+         * Display the correct position on the status bar, if the
+         * percent parameter is omitted it will be calculated.
+         *
+         * Negative numbers are set to "All", Zero implies "Top"
+         * One or above is "Bot", and anything else is multiplied by
+         * a hundred and displayed as a percentage.
+         *
+         * @param {number} percent
+         */
         updateBufferPosition: function updateBufferPosition(percent)
         {
             if (!percent || typeof percent != "number")