From e91fbcd75470c13a1305641b0aa070a92c93d6bf Mon Sep 17 00:00:00 2001 From: Doug Kearns Date: Fri, 2 Jan 2009 00:51:45 +1100 Subject: [PATCH] Add some source documentation for AutoCommands. Also normalise the use of /* */ and // comments. --- common/content/buffer.js | 2 +- common/content/commands.js | 8 +-- common/content/completion.js | 97 +++++++++++++++++------------------- common/content/editor.js | 2 +- common/content/events.js | 58 ++++++++++++++++++--- common/content/find.js | 1 - common/content/liberator.js | 25 ++++++---- common/content/options.js | 4 +- common/content/services.js | 2 +- common/content/style.js | 7 ++- common/content/template.js | 4 +- common/content/ui.js | 11 ++-- muttator/content/mail.js | 13 ++--- vimperator/regressions.js | 8 +-- 14 files changed, 143 insertions(+), 99 deletions(-) diff --git a/common/content/buffer.js b/common/content/buffer.js index 3ebac019..acbaf90c 100644 --- a/common/content/buffer.js +++ b/common/content/buffer.js @@ -42,7 +42,7 @@ function Buffer() //{{{ ////////////////////// PRIVATE SECTION ///////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////{{{ - /* FIXME: This doesn't belong here. */ + // FIXME: This doesn't belong here. let mainWindowID = config.mainWindowID || "main-window"; let fontSize = util.computedStyle(document.getElementById(mainWindowID)).fontSize; diff --git a/common/content/commands.js b/common/content/commands.js index 9da223f1..a45d7b16 100644 --- a/common/content/commands.js +++ b/common/content/commands.js @@ -28,14 +28,14 @@ the terms of any one of the MPL, the GPL or the LGPL. /** @scope modules */ +// Do NOT create instances of this class yourself, use the helper method +// commands.add() instead /** * A class representing Ex commands. Instances are created by * the {@link Commands} class. * * @private */ -// Do NOT create instances of this class yourself, use the helper method -// commands.add() instead function Command(specs, description, action, extraInfo) //{{{ { if (!specs || !action) @@ -112,7 +112,7 @@ function Command(specs, description, action, extraInfo) //{{{ * arguments begin. For instance, with a value of 2, all arguments * starting with the third are parsed as a single string, with all * quoting characters passed literally. This is especially useful for - * commands which take key mappings or ex command lines as + * commands which take key mappings or Ex command lines as * arguments. */ this.literal = extraInfo.literal == null ? null : extraInfo.literal; @@ -133,7 +133,7 @@ function Command(specs, description, action, extraInfo) //{{{ this.isUserCommand = extraInfo.isUserCommand || false; /** * @property {string} For commands defined via :command, contains - * the EX command line to be executed upon invocation. + * the Ex command line to be executed upon invocation. */ this.replacementText = extraInfo.replacementText || null; }; diff --git a/common/content/completion.js b/common/content/completion.js index dc4ba9ed..a21e098b 100644 --- a/common/content/completion.js +++ b/common/content/completion.js @@ -683,10 +683,10 @@ function Completion() //{{{ const OFFSET = 0, CHAR = 1, STATEMENTS = 2, DOTS = 3, FULL_STATEMENTS = 4, COMMA = 5, FUNCTIONS = 6; let stack = []; let functions = []; - let top = []; /* The element on the top of the stack. */ - let last = ""; /* The last opening char pushed onto the stack. */ - let lastNonwhite = ""; /* Last non-whitespace character we saw. */ - let lastChar = ""; /* Last character we saw, used for \ escaping quotes. */ + let top = []; // The element on the top of the stack. + let last = ""; // The last opening char pushed onto the stack. + let lastNonwhite = ""; // Last non-whitespace character we saw. + let lastChar = ""; // Last character we saw, used for \ escaping quotes. let compl = []; let str = ""; @@ -733,11 +733,10 @@ function Completion() //{{{ return iterator; } - /* Search the object for strings starting with @key. - * If @last is defined, key is a quoted string, it's - * wrapped in @last after @offset characters are sliced - * off of it and it's quoted. - */ + // Search the object for strings starting with @key. + // If @last is defined, key is a quoted string, it's + // wrapped in @last after @offset characters are sliced + // off of it and it's quoted. this.objectKeys = function objectKeys(obj) { // Things we can dereference @@ -809,11 +808,10 @@ function Completion() //{{{ } } - /* Get an element from the stack. If @n is negative, - * count from the top of the stack, otherwise, the bottom. - * If @m is provided, return the @mth value of element @o - * of the stack entey at @n. - */ + // Get an element from the stack. If @n is negative, + // count from the top of the stack, otherwise, the bottom. + // If @m is provided, return the @mth value of element @o + // of the stack entey at @n. let get = function get(n, m, o) { let a = stack[n >= 0 ? n : stack.length + n]; @@ -827,7 +825,7 @@ function Completion() //{{{ function buildStack(filter) { let self = this; - /* Push and pop the stack, maintaining references to 'top' and 'last'. */ + // Push and pop the stack, maintaining references to 'top' and 'last'. let push = function push(arg) { top = [i, arg, [i], [], [], [], []]; @@ -855,7 +853,7 @@ function Completion() //{{{ return ret; } - let i = 0, c = ""; /* Current index and character, respectively. */ + let i = 0, c = ""; // Current index and character, respectively. // Reuse the old stack. if (str && filter.substr(0, str.length) == str) @@ -871,11 +869,10 @@ function Completion() //{{{ push("#root"); } - /* Build a parse stack, discarding entries as opening characters - * match closing characters. The stack is walked from the top entry - * and down as many levels as it takes us to figure out what it is - * that we're completing. - */ + // Build a parse stack, discarding entries as opening characters + // match closing characters. The stack is walked from the top entry + // and down as many levels as it takes us to figure out what it is + // that we're completing. str = filter; let length = str.length; for (; i < length; lastChar = c, i++) @@ -907,7 +904,7 @@ function Completion() //{{{ switch (c) { case "(": - /* Function call, or if/while/for/... */ + // Function call, or if/while/for/... if (/[\w$]/.test(lastNonwhite)) { functions.push(i); @@ -928,7 +925,7 @@ function Completion() //{{{ break; case ")": pop("("); break; case "]": pop("["); break; - case "}": pop("{"); /* Fallthrough */ + case "}": pop("{"); // Fallthrough case ";": top[FULL_STATEMENTS].push(i); break; @@ -973,7 +970,7 @@ function Completion() //{{{ this.context.getCache("eval", Object); this.context.getCache("evalContext", function () ({ __proto__: userContext })); - /* Okay, have parse stack. Figure out what we're completing. */ + // Okay, have parse stack. Figure out what we're completing. // Find any complete statements that we can eval before we eval our object. // This allows for things like: let doc = window.content.document; let elem = doc.createElement...; elem. @@ -1040,7 +1037,7 @@ function Completion() //{{{ cacheKey = null; let obj = [[cache.evalContext, "Local Variables"], [userContext, "Global Variables"], [modules, "modules"], [window, "window"]]; // Default objects; - /* Is this an object dereference? */ + // Is this an object dereference? if (dot < statement) // No. dot = statement - 1; else // Yes. Set the object to the string before the dot. @@ -1113,11 +1110,11 @@ function Completion() //{{{ // Otherwise, do nothing. if (last == "'" || last == '"') { - /* - * str = "foo[bar + 'baz" - * obj = "foo" - * key = "bar + ''" - */ + // + // str = "foo[bar + 'baz" + // obj = "foo" + // key = "bar + ''" + // // The top of the stack is the sting we're completing. // Wrap it in its delimiters and eval it to process escape sequences. @@ -1134,14 +1131,13 @@ function Completion() //{{{ return this.eval(key); } - /* Is this an object accessor? */ + // Is this an object accessor? if (get(-2)[CHAR] == "[") // Are we inside of []? { - /* Stack: - * [-1]: "... - * [-2]: [... - * [-3]: base statement - */ + // Stack: + // [-1]: "... + // [-2]: [... + // [-3]: base statement // Yes. If the [ starts at the beginning of a logical // statement, we're in an array literal, and we're done. @@ -1157,11 +1153,10 @@ function Completion() //{{{ // Is this a function call? if (get(-2)[CHAR] == "(") { - /* Stack: - * [-1]: "... - * [-2]: (... - * [-3]: base statement - */ + // Stack: + // [-1]: "... + // [-2]: (... + // [-3]: base statement // Does the opening "(" mark a function call? if (get(-3, 0, FUNCTIONS) != get(-2)[OFFSET]) @@ -1210,15 +1205,15 @@ function Completion() //{{{ return; } - /* - * str = "foo.bar.baz" - * obj = "foo.bar" - * key = "baz" - * - * str = "foo" - * obj = [modules, window] - * key = "foo" - */ + // + // str = "foo.bar.baz" + // obj = "foo.bar" + // key = "baz" + // + // str = "foo" + // obj = [modules, window] + // key = "foo" + // let [offset, obj, key] = getObjKey(-1); @@ -1231,7 +1226,7 @@ function Completion() //{{{ } if (!/^(?:[a-zA-Z_$][\w$]*)?$/.test(key)) - return; /* Not a word. Forget it. Can this even happen? */ + return; // Not a word. Forget it. Can this even happen? try { // FIXME diff --git a/common/content/editor.js b/common/content/editor.js index 182a654d..4fe4ed4b 100644 --- a/common/content/editor.js +++ b/common/content/editor.js @@ -217,7 +217,7 @@ function Editor() //{{{ var myModes = [modes.INSERT, modes.COMMAND_LINE]; - /* KEYS COUNT CARET TEXTAREA VISUAL_TEXTAREA */ + // KEYS COUNT CARET TEXTAREA VISUAL_TEXTAREA addMovementMap(["k", ""], true, "lineMove", false, "cmd_linePrevious", selectPreviousLine); addMovementMap(["j", "", ""], true, "lineMove", true, "cmd_lineNext", selectNextLine); addMovementMap(["h", "", ""], true, "characterMove", false, "cmd_charPrevious", "cmd_selectCharPrevious"); diff --git a/common/content/events.js b/common/content/events.js index a34c2f92..5e3d3ec4 100644 --- a/common/content/events.js +++ b/common/content/events.js @@ -182,6 +182,16 @@ function AutoCommands() //{{{ __iterator__: function () util.Array.iterator(store), + /** + * Adds a new autocommand. cmd will be executed when one of the + * specified events occurs and the URL of the applicable buffer + * matches regex. + * + * @param {Array} events The array of event names for which this + * autocommand should be executed. + * @param {string} regex The URL pattern to match against the buffer URL + * @param {string} cmd The Ex command to run + */ add: function (events, regex, cmd) { if (typeof events == "string") @@ -194,16 +204,38 @@ function AutoCommands() //{{{ }); }, + /** + * Returns all autocommands with a matching event and + * regex. + * + * @param {string} event The event name filter. + * @param {string} regex The URL pattern filter. + * @returns {AutoCommand[]} + */ get: function (event, regex) { return store.filter(function (autoCmd) matchAutoCmd(autoCmd, event, regex)); }, + /** + * Deletes all autocommands with a matching event and + * regex. + * + * @param {string} event The event name filter. + * @param {string} regex The URL pattern filter. + */ remove: function (event, regex) { store = store.filter(function (autoCmd) !matchAutoCmd(autoCmd, event, regex)); }, + /** + * Lists all autocommands with a matching event and + * regex. + * + * @param {string} event The event name filter. + * @param {string} regex The URL pattern filter. + */ list: function (event, regex) { let cmds = {}; @@ -239,6 +271,14 @@ function AutoCommands() //{{{ commandline.echo(list, commandline.HL_NORMAL, commandline.FORCE_MULTILINE); }, + /** + * Triggers the execution of all autocommands registered for + * event. A map of args is passed to each autocommand + * when it is being executed. + * + * @param {string} event The event to fire. + * @param {Object} args The args to pass to each autocommand. + */ trigger: function (event, args) { if (options.get("eventignore").has("all", event)) @@ -835,12 +875,18 @@ function Events() //{{{ } }, - // This method pushes keys into the event queue from liberator - // 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 - // if you want < to be taken literally, prepend it with a \\ + /** + * Pushes keys into the event queue from liberator it is similar to + * Vim's feedkeys() method, but cannot cope with 2 partially-fed + * strings, you have to feed one parsable string. + * + * @param {string} keys A string like "2" to pass if you want "<" + * to be taken literally, prepend it with a "\\". + * @param {boolean} noremap Allow recursive mappings. + * @param {boolean} silent Whether the command should be echoed to the + * command-line. + * @returns {boolean} + */ feedkeys: function (keys, noremap, silent) { let doc = window.document; diff --git a/common/content/find.js b/common/content/find.js index f289e20c..0bb125cb 100644 --- a/common/content/find.js +++ b/common/content/find.js @@ -469,7 +469,6 @@ function Search() //{{{ // highlighted getBrowser().fastFind.collapseSelection(); } - }; //}}} }; //}}} diff --git a/common/content/liberator.js b/common/content/liberator.js index cc0b78e9..49b106a4 100644 --- a/common/content/liberator.js +++ b/common/content/liberator.js @@ -1057,16 +1057,21 @@ const liberator = (function () //{{{ consoleService.logStringMessage(config.name.toLowerCase() + ": " + msg); }, - // open one or more URLs - // - // @param urls: either a string or an array of urls - // The array can look like this: - // ["url1", "url2", "url3", ...] or: - // [["url1", postdata1], ["url2", postdata2], ...] - // @param where: if ommited, CURRENT_TAB is assumed - // but NEW_TAB is set when liberator.forceNewTab is true. - // @param force: Don't prompt whether to open more than 20 tabs. - // @returns true when load was initiated, or false on error + /** + * Opens one or more URLs. Returns true when load was initiated, or + * false on error. + * + * @param {FIXME} urls Either a URL string or an array of URLs. + * The array can look like this: + * ["url1", "url2", "url3", ...] + * or: + * [["url1", postdata1], ["url2", postdata2], ...] + * @param {number} where If ommited, CURRENT_TAB is assumed but NEW_TAB + * is set when liberator.forceNewTab is true. + * @param {boolean} force Don't prompt whether to open more than 20 + * tabs. + * @returns {boolean} + */ open: function (urls, where, force) { // convert the string to an array of converted URLs diff --git a/common/content/options.js b/common/content/options.js index ca959504..ed4a2cb4 100644 --- a/common/content/options.js +++ b/common/content/options.js @@ -867,7 +867,7 @@ function Options() //{{{ isDefault: opt.value == opt.defaultValue, name: opt.name, default: opt.defaultValue, - pre: "\u00a0\u00a0", /* Unicode nonbreaking space. */ + pre: "\u00a0\u00a0", // Unicode nonbreaking space. value: <> }; @@ -915,7 +915,7 @@ function Options() //{{{ default: loadPreference(pref, null, true), value: <>={template.highlight(value, true, 100)}, name: pref, - pre: "\u00a0\u00a0" /* Unicode nonbreaking space. */ + pre: "\u00a0\u00a0" // Unicode nonbreaking space. }; yield option; diff --git a/common/content/services.js b/common/content/services.js index 2b22c702..57d8a0c9 100644 --- a/common/content/services.js +++ b/common/content/services.js @@ -15,7 +15,7 @@ const Cu = Components.utils; /** * Cached XPCOM services and instances. - * + * * @constructor */ function Services() diff --git a/common/content/style.js b/common/content/style.js index 1a693230..6d6bfaef 100644 --- a/common/content/style.js +++ b/common/content/style.js @@ -246,10 +246,9 @@ function Highlights(name, store, serial) */ function Styles(name, store, serial) { - /* Can't reference liberator or Components inside Styles -- - * they're members of the window object, which disappear - * with this window. - */ + // Can't reference liberator or Components inside Styles -- + // they're members of the window object, which disappear + // with this window. const util = modules.util; const sleep = liberator.sleep; const storage = modules.storage; diff --git a/common/content/template.js b/common/content/template.js index 0baaaf00..60f986df 100644 --- a/common/content/template.js +++ b/common/content/template.js @@ -7,7 +7,7 @@ const template = { map: function map(iter, fn, sep, interruptable) { - if (iter.length) /* Kludge? */ + if (iter.length) // FIXME: Kludge? iter = util.Array.iterator(iter); let ret = <>; let n = 0; @@ -287,7 +287,7 @@ const template = { tabular: function tabular(headings, style, iter) { - /* This might be mind-bogglingly slow. We'll see. */ + // TODO: This might be mind-bogglingly slow. We'll see. // return this.commandOutput( diff --git a/common/content/ui.js b/common/content/ui.js index 84b230be..28aeb3f7 100644 --- a/common/content/ui.js +++ b/common/content/ui.js @@ -28,7 +28,7 @@ the terms of any one of the MPL, the GPL or the LGPL. /** @scope modules */ -/* +/** * This class is used for prompting of user input and echoing of messages * * it consists of a prompt and command field @@ -560,11 +560,10 @@ function CommandLine() //{{{ liberator.triggerObserver("echoMultiline", str, highlightGroup); - /* If it's already XML, assume it knows what it's doing. - * Otherwise, white space is significant. - * The problem elsewhere is that E4X tends to insert new lines - * after interpolated data. - */ + // If it's already XML, assume it knows what it's doing. + // Otherwise, white space is significant. + // The problem elsewhere is that E4X tends to insert new lines + // after interpolated data. XML.ignoreWhitespace = typeof str != "xml"; lastMowOutput =
{template.maybeXML(str)}
; let output = util.xmlToDom(lastMowOutput, doc); diff --git a/muttator/content/mail.js b/muttator/content/mail.js index 0fc6fa13..c8513d7c 100644 --- a/muttator/content/mail.js +++ b/muttator/content/mail.js @@ -890,12 +890,13 @@ function Mail() //{{{ return false; }, - /* - * general-purpose method to find messages - * @param validatorFunc(msg): return true/false whether msg should be selected or not - * @param canWrap: when true, wraps around folders - * @param openThreads: should we open closed threads? - * @param reverse: change direction of searching + /** + * General-purpose method to find messages + * + * @param {function} validatorFunc(msg): return true/false whether msg should be selected or not + * @param {boolean} canWrap: when true, wraps around folders + * @param {boolean} openThreads: should we open closed threads? + * @param {boolean} reverse: change direction of searching */ selectMessage: function (validatorFunc, canWrap, openThreads, reverse, count) { diff --git a/vimperator/regressions.js b/vimperator/regressions.js index 5453d4d7..0bf605d1 100644 --- a/vimperator/regressions.js +++ b/vimperator/regressions.js @@ -28,9 +28,9 @@ var singlelineOutput = document.getElementById("liberator-commandline-command") // previous command ///////////////////////////////////////////////////////////////////////////////////////// -// A series of ex commands or mappings, each with a +// A series of Ex commands or mappings, each with a // function checking whether the command succeeded -// If the string starts with a ":" it is executed as an ex command, otherwise as a mapping +// If the string starts with a ":" it is executed as an Ex command, otherwise as a mapping // You can also mix commands mappings let tests = [ { cmds: [":!dir"], @@ -56,7 +56,7 @@ let tests = [ // testing tab behavior ]; -// these functions highly depend on the liberator API, so use ex command tests whenever possible +// these functions highly depend on the liberator API, so use Ex command tests whenever possible let functions = [ function () { return bookmarks.get("").length > 0 }, // will fail for people without bookmarks :( Might want to add one before function () { return history.get("").length > 0 } @@ -120,7 +120,7 @@ commands.addUserCommand(["regr[essions]"], // TODO: count (better even range) support to just run test 34 of 102 // TODO: bang support to either: a) run commands like deleting bookmarks which // should only be done in a clean profile or b) run functions and not - // just ex command tests; Yet to be decided + // just Ex command tests; Yet to be decided let updateOutputHeight = null; function init()