diff --git a/common/content/buffer.js b/common/content/buffer.js index 4d5e3b41..2a5b3ff4 100644 --- a/common/content/buffer.js +++ b/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 - * returns stylesheets for the 'screen' media type. + * @property {Array} The alternative stylesheets for the current + * 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: - * 0 - Loading. - * 1 - Fully loaded. - * 2 - Load failed. + * @property {number} A value indicating whether the buffer is loaded. + * Values may be: + * 0 - Loading. + * 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 - * "gi" key binding. + * @property {Object} The last focused input field in the buffer. Used + * 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 - * 100 as 'normal'. Only affects text size. + * @property {number} The current browser's text zoom level, as a + * 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 - * 100 as 'normal'. Affects text size, as well as image size - * and block size. + * @property {number} The current browser's text zoom level, as a + * percentage with 100 as 'normal'. Affects text size, as well as + * 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 - * has a singularly horrendous name, it turns out to be quite - * useful. + * Tries to guess links the like of "next" and "prev". Though it has a + * singularly horrendous name, it turns out to be quite 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 count * '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 percentage + * Scrolls the current buffer vertically to percentage. + * + * @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:
{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 url. 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); diff --git a/common/content/commands.js b/common/content/commands.js index 15726961..9da223f1 100644 --- a/common/content/commands.js +++ b/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 name. * * @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 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 if they didn't want it) return "<"; let res = tokens[token]; if (res == undefined) // Ignore anything undefined diff --git a/common/content/completion.js b/common/content/completion.js index 63e803aa..dc4ba9ed 100644 --- a/common/content/completion.js +++ b/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 . 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 - * that it's worth breaking compatibility. - */ + // Not Vim compatible, but is a significant enough improvement + // that it's worth breaking compatibility. if (newValues instanceof Array) { completions = completions.filter(function (val) newValues.indexOf(val[0]) == -1); diff --git a/common/content/editor.js b/common/content/editor.js index efebefd3..efda6794 100644 --- a/common/content/editor.js +++ b/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 diff --git a/common/content/events.js b/common/content/events.js index 33cb4380..a34c2f92 100644 --- a/common/content/events.js +++ b/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" 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 (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 != "" && key != "") { - // 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) diff --git a/common/content/find.js b/common/content/find.js index 8e67fbb4..f289e20c 100644 --- a/common/content/find.js +++ b/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) { diff --git a/common/content/hints.js b/common/content/hints.js index edca3fb6..4ddaa980 100644 --- a/common/content/hints.js +++ b/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 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) diff --git a/common/content/io.js b/common/content/io.js index 0e7ff6bb..79f20f28 100644 --- a/common/content/io.js +++ b/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 < */ @@ -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 */ @@ -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 filter 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) diff --git a/common/content/ui.js b/common/content/ui.js index b0edf3e5..84b230be 100644 --- a/common/content/ui.js +++ b/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 , 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 "": case "": case "": @@ -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