Cleanup some docs. Fix completion sizing bug.

common/content/io.js

@@ -504,7 +504,7 @@ function IO() //{{{
          * Sets the current working directory.
          *
          * @param {string} newDir The new CWD. This may be a relative or
-         *     absolute path and is expanded by (@link #expandPath).
+         *     absolute path and is expanded by {@link #expandPath}.
          */
         setCurrentDirectory: function (newDir)
         {
@@ -713,16 +713,16 @@ function IO() //{{{
          * @param {string} buf The file content.
          * @param {string|number} mode The file access mode, a bitwise OR of
          *     the following flags:
-         *       (@link #MODE_RDONLY):   0x01
+         *       {@link #MODE_RDONLY}:   0x01
-         *       (@link #MODE_WRONLY):   0x02
+         *       {@link #MODE_WRONLY}:   0x02
-         *       (@link #MODE_RDWR):     0x04
+         *       {@link #MODE_RDWR}:     0x04
-         *       (@link #MODE_CREATE):   0x08
+         *       {@link #MODE_CREATE}:   0x08
-         *       (@link #MODE_APPEND):   0x10
+         *       {@link #MODE_APPEND}:   0x10
-         *       (@link #MODE_TRUNCATE): 0x20
+         *       {@link #MODE_TRUNCATE}: 0x20
-         *       (@link #MODE_SYNC):     0x40
+         *       {@link #MODE_SYNC}:     0x40
          *     Alternatively, the following abbreviations may be used:
-         *       ">"  is equivalent to (@link #MODE_WRONLY) | (@link #MODE_CREATE) | (@link #MODE_TRUNCATE)
+         *       ">"  is equivalent to {@link #MODE_WRONLY} | {@link #MODE_CREATE} | {@link #MODE_TRUNCATE}
-         *       ">>" is equivalent to (@link #MODE_WRONLY) | (@link #MODE_CREATE) | (@link #MODE_APPEND)
+         *       ">>" is equivalent to {@link #MODE_WRONLY} | {@link #MODE_CREATE} | {@link #MODE_APPEND}
          * @default ">"
          * @param {number} perms The file mode bits of the created file. This
          *     is only used when creating a new file and does not change
@@ -1053,20 +1053,17 @@ lookup:
                 }
                 else
                 {
-
                     this.writeFile(cmd, "cd " + escape(cwd.path) + "\n" +
                             ["exec", ">" + escape(stdout.path), "2>&1", "<" + escape(stdin.path),
                              escape(options["shell"]), options["shellcmdflag"], escape(command)].join(" "));
                     res = this.run("/bin/sh", ["-e", cmd.path], true);
                 }
 
+                let output = self.readFile(stdout);
                 if (res > 0)
-                    var output = self.readFile(stdout) + "\nshell returned " + res;
+                    output += "\nshell returned " + res;
-                else
-                    output = self.readFile(stdout);
-
                 // if there is only one \n at the end, chop it off
-                if (output && output.indexOf("\n") == output.length - 1)
+                else if (output && output.indexOf("\n") == output.length - 1)
                     output = output.substr(0, output.length - 1);
 
                 return output;
@@ -1076,10 +1073,13 @@ lookup:
         /**
          * Creates a temporary file context for executing external commands.
          * <b>fn</b> is called with a temp file, created with
-         * {@link #createTempFile}, as each argument.
+         * {@link #createTempFile}, for each explicit argument. Ensures that
+         * all files are removed when <b>fn</b> returns.
          * 
-         * @param {function} fn The fn to execute.
+         * @param {function} fn The function to execute.
-         * @param {Object} self The calling object used when executing fn.
+         * @param {Object} self The 'this' object used when executing fn.
+         * @return {boolean} false if temp files couldn't be created,
+         *     otherwise, the return value of <b>fn</b>.
          */
         withTempFiles: function (fn, self)
         {

common/content/options.js

@@ -1015,17 +1015,38 @@ function Options() //{{{
                 liberator.echoerr("E488: Trailing characters: " + name + "!");
         },
 
+        /**
+         * Pushes a new preference context onto the context stack.
+         *
+         * @see #withContext
+         */
         pushContext: function ()
         {
             prefContexts.push({});
         },
 
+        /**
+         * Pops the top preference context from the stack.
+         *
+         * @see #withContext
+         */
         popContext: function ()
         {
             for (let [k, v] in Iterator(prefContexts.pop()))
                 storePreference(k, v);
         },
 
+        /**
+         * Executes <b>fn</b> with a new preference context. When <b>fn</b>
+         * returns, the context is popped and any preferences set via
+         * {@link #setPref} or {@link #invertPref} are restored to their
+         * previous values.
+         *
+         * @param {function} fn The function to call.
+         * @param {object} fn The 'this' object with which to call <b>fn</b>
+         * @see #pushContext
+         * @see #popContext
+         */
         withContext: function (fn, self)
         {
             try

common/content/ui.js

@@ -1596,6 +1596,13 @@ function CommandLine() //{{{
             }
         },
 
+        getSpaceNeeded: function getSpaceNeeded()
+        {
+            let rect = commandlineWidget.getBoundingClientRect();
+            let offset = rect.bottom - window.innerHeight;
+            return Math.max(0, offset);
+        },
+
         /**
          * Update or remove the multiline output widget's "MORE" prompt.
          *
@@ -1635,13 +1642,13 @@ function CommandLine() //{{{
 
             let doc = multilineOutputWidget.contentDocument;
 
-            // The container needs to be collapsed for this calculation to work.
-            outputContainer.collapsed = true;
             let availableHeight = 250;
             try
             {
                 availableHeight = getBrowser().mPanelContainer ?
                     getBrowser().mPanelContainer.boxObject.height : getBrowser().boxObject.height;
+                if (!outputContainer.collapsed)
+                    availableHeight += outputContainer.height;
             }
             catch (e) {}
             doc.body.style.minWidth = commandlineWidget.scrollWidth + "px";
@@ -1723,6 +1730,7 @@ function ItemList(id) //{{{
             div.style.minWidth = "";
         // FIXME: Belongs elsewhere.
         commandline.updateOutputHeight(false);
+        container.height -= commandline.getSpaceNeeded();
     }
 
     function getCompletion(index) completionElements.snapshotItem(index - startIndex);