diff options
| -rw-r--r-- | common/content/buffer.js | 9 | ||||
| -rw-r--r-- | common/content/commands.js | 4 | ||||
| -rw-r--r-- | common/content/completion.js | 1 | ||||
| -rw-r--r-- | common/content/configbase.js | 4 | ||||
| -rw-r--r-- | common/content/events.js | 46 | ||||
| -rw-r--r-- | common/content/hints.js | 19 | ||||
| -rw-r--r-- | common/content/io.js | 6 | ||||
| -rw-r--r-- | common/content/liberator.js | 157 | ||||
| -rw-r--r-- | common/content/style.js | 2 | ||||
| -rw-r--r-- | common/content/ui.js | 3 | ||||
| -rw-r--r-- | common/content/util.js | 5 | ||||
| -rw-r--r-- | muttator/content/config.js | 1 | ||||
| -rw-r--r-- | vimperator/TODO | 1 | ||||
| -rw-r--r-- | vimperator/content/config.js | 1 |
14 files changed, 193 insertions, 66 deletions
diff --git a/common/content/buffer.js b/common/content/buffer.js index 0f026db0..70a41512 100644 --- a/common/content/buffer.js +++ b/common/content/buffer.js @@ -1028,8 +1028,8 @@ function Buffer() //{{{ * @default The current document. * @param {Node} elem The context element. * @default <b>doc</b> - * @param {boolean} asIterator Whether to return the results as an XPath - * iterator. + * @param {boolean} asIterator Whether to return the results as an + * XPath iterator. */ evaluateXPath: function (expression, doc, elem, asIterator) { @@ -1510,7 +1510,7 @@ function Buffer() //{{{ /** * Displays information about the specified element. * - * @param {Node} elem + * @param {Node} elem The element to query. */ showElementInfo: function (elem) { @@ -1848,7 +1848,8 @@ function Marks() //{{{ * selected from. If it matches [a-z'"], it's a local mark, and can * only be recalled from a buffer with a matching URL. * - * @param {string} mark + * @param {string} mark The mark name. + * @param {boolean} silent Whether to output error messages. */ // TODO: add support for frameset pages add: function (mark, silent) diff --git a/common/content/commands.js b/common/content/commands.js index e201619f..d9bb49a2 100644 --- a/common/content/commands.js +++ b/common/content/commands.js @@ -181,7 +181,7 @@ Command.prototype = { * @param {string} args The args to be parsed and passed to * {@link #action}. * @param {boolean} bang Whether this command was executed with a trailing - * !. + * bang. * @deprecated * @param {number} count Whether this command was executed with a leading * count. @@ -224,7 +224,7 @@ Command.prototype = { /** * Returns whether this command may be invoked via <b>name</b>. * - * @param {string} name + * @param {string} name The candidate name. * @returns {boolean} */ hasName: function (name) diff --git a/common/content/completion.js b/common/content/completion.js index 07f0cbb3..0726032f 100644 --- a/common/content/completion.js +++ b/common/content/completion.js @@ -547,6 +547,7 @@ CompletionContext.prototype = { /** * Gets a key from {@link #cache}, setting it to <b>defVal</b> if it * doesn't already exists. + * * @param {string} key * @param defVal */ diff --git a/common/content/configbase.js b/common/content/configbase.js index 4f8282f0..eb670463 100644 --- a/common/content/configbase.js +++ b/common/content/configbase.js @@ -37,7 +37,7 @@ const configbase = { //{{{ get browserModes() [modes.NORMAL], /** - * @property {object} Application specific defaults for option values. The + * @property {Object} Application specific defaults for option values. The * property names must be the options' canonical names, and the values * must be strings as entered via :set. */ @@ -86,7 +86,7 @@ const configbase = { //{{{ init: function () {}, /** - * @property {object} A map between key names for key events should be ignored, + * @property {Object} A map between key names for key events should be ignored, * and a mask of the modes in which they should be ignored. */ ignoreKeys: {}, // XXX: be aware you can't put useful values in here, as "modes.NORMAL" etc. are not defined at this time diff --git a/common/content/events.js b/common/content/events.js index 6f1dfda0..c2e10902 100644 --- a/common/content/events.js +++ b/common/content/events.js @@ -479,7 +479,7 @@ function Events() //{{{ let elem = liberator.focus; return ((elem instanceof HTMLInputElement && !/image/.test(elem.type)) || elem instanceof HTMLTextAreaElement || - elem instanceof HTMLIsIndexElement) + elem instanceof HTMLIsIndexElement); } function triggerLoadAutocmd(name, doc) @@ -965,18 +965,21 @@ function Events() //{{{ }, /** - * Converts a user-input string of keys into a canonical representation. + * Converts a user-input string of keys into a canonical + * representation. * * <C-A> maps to <C-a>, <C-S-a> maps to <C-S-A> * <C- > maps to <C-Space>, <S-a> maps to A * << maps to <lt><lt> * - * <S-@> is preserved, as in vim, to allow untypable key-combinations in macros + * <S-@> is preserved, as in vim, to allow untypable key-combinations + * in macros. * - * canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values of x. + * canonicalKeys(canonicalKeys(x)) == canonicalKeys(x) for all values + * of x. * - * @param {String} keys messy form - * @returns {String} canonical form + * @param {string} keys Messy form. + * @returns {string} Canonical form. */ canonicalKeys: function (keys) { @@ -986,16 +989,18 @@ function Events() //{{{ /** * Converts an event string into an array of pseudo-event objects. * - * These objects can be used as arguments to events.toString or events.create, - * though they are unlikely to be much use for other purposes. They have many - * of the properties you'd expect to find on a real event, but none of the methods. + * These objects can be used as arguments to events.toString or + * events.create, though they are unlikely to be much use for other + * purposes. They have many of the properties you'd expect to find on a + * real event, but none of the methods. * - * Also may contain two "special" parameters, .liberatorString and .liberatorShift - * these are set for characters that can never by typed, but may appear in mappings, - * for example <Nop> is passed as liberatorString, and liberatorShift is set when - * a user specifies <S-@> where @ is a non-case-changable, non-space character. + * Also may contain two "special" parameters, .liberatorString and + * .liberatorShift these are set for characters that can never by + * typed, but may appear in mappings, for example <Nop> is passed as + * liberatorString, and liberatorShift is set when a user specifies + * <S-@> where @ is a non-case-changable, non-space character. * - * @param {String} keys The string to parse + * @param {string} keys The string to parse. * @return {Array[Object]} */ fromString: function (input) @@ -1082,7 +1087,7 @@ function Events() //{{{ * @param {Event} event * @returns {string} */ - toString: function (event, all) + toString: function (event) { if (!event) return "[object Mappings]"; @@ -1197,6 +1202,7 @@ function Events() //{{{ * Whether <b>key</b> is a key code defined to accept/execute input on * the command line. * + * @param {string} key The key code to test. * @returns {boolean} */ isAcceptKey: function (key) key == "<Return>" || key == "<C-j>" || key == "<C-m>", @@ -1205,11 +1211,12 @@ function Events() //{{{ * Whether <b>key</b> is a key code defined to reject/cancel input on * the command line. * + * @param {string} key The key code to test. * @returns {boolean} */ isCancelKey: function (key) key == "<Esc>" || key == "<C-[>" || key == "<C-c>", - /* + /** * Waits for the current buffer to successfully finish loading. Returns * true for a successful page load otherwise false. * @@ -1346,7 +1353,9 @@ function Events() //{{{ // } }, - // global escape handler, is called in ALL modes + /** + * The global escape key handler. This is called in ALL modes. + */ onEscape: function () { if (modes.passNextKey) @@ -1665,6 +1674,9 @@ function Events() //{{{ }, // TODO: move to buffer.js? + /** + * The liberator document loading progress listener. + */ progressListener: { QueryInterface: XPCOMUtils.generateQI([ Ci.nsIWebProgressListener, diff --git a/common/content/hints.js b/common/content/hints.js index c0556708..5ca4e1ea 100644 --- a/common/content/hints.js +++ b/common/content/hints.js @@ -217,7 +217,7 @@ function Hints() //{{{ try { // Need to add the offset to the area element. - // Always try to find the top-left point, as per vimperator default. + // Always try to find the top-left point, as per liberator default. let shape = elem.getAttribute("shape").toLowerCase(); let coordstr = elem.getAttribute("coords"); // Technically it should be only commas, but hey @@ -352,8 +352,8 @@ function Hints() //{{{ * * By default highlights it green instead of yellow. * - * @param {Number} newID The hint to make active - * @param {Number} oldID The currently active hint + * @param {number} newID The hint to make active. + * @param {number} oldID The currently active hint. */ function showActiveHint(newID, oldID) { @@ -624,7 +624,7 @@ function Hints() //{{{ * would match the first letters of words. It will always only match * words in order. * - * @param {String} hintString The string typed by the user. + * @param {string} hintString The string typed by the user. * @param {boolean} allowWordOverleaping Whether to allow non-contiguous * words to match. * @returns {function(String):boolean} A function that will filter only @@ -893,15 +893,16 @@ function Hints() //{{{ * Creates a new hint mode. * * @param {string} mode The letter that identifies this mode. - * @param {string} description The description to display to the user + * @param {string} prompt The description to display to the user * about this mode. - * @param {function(Node)} callback The function to be called with the + * @param {function(Node)} action The function to be called with the * element that matches. - * @param {function():string} selector The function that returns an - * XPath selector to decide which elements can be hinted (the + * @param {function():string} tags The function that returns an + * XPath expression to decide which elements can be hinted (the * default returns options.hinttags). + * @optional */ - addMode: function (mode) + addMode: function (mode, prompt, action, tags) { hintModes[mode] = Mode.apply(Mode, Array.slice(arguments, 1)); }, diff --git a/common/content/io.js b/common/content/io.js index 38bf5915..815c15db 100644 --- a/common/content/io.js +++ b/common/content/io.js @@ -65,7 +65,7 @@ function IO() //{{{ /////////////////////////////////////////////////////////////////////////////{{{ const WINDOWS = liberator.has("Win32"); - const EXTENSION_NAME = config.name.toLowerCase(); // "vimperator" or "muttator" + const EXTENSION_NAME = config.name.toLowerCase(); const downloadManager = Cc["@mozilla.org/download-manager;1"].createInstance(Ci.nsIDownloadManager); @@ -569,7 +569,7 @@ function IO() //{{{ expandPath: IO.expandPath, // TODO: there seems to be no way, short of a new component, to change - // the process's CWD - see // https://bugzilla.mozilla.org/show_bug.cgi?id=280953 + // the process's CWD - see https://bugzilla.mozilla.org/show_bug.cgi?id=280953 /** * Returns the current working directory. * @@ -1119,7 +1119,7 @@ lookup: }, // TODO: when https://bugzilla.mozilla.org/show_bug.cgi?id=68702 is - // fixed is fixed, should use that instead of a tmpfile + // fixed use that instead of a tmpfile /** * Runs <b>command</b> in a subshell and returns the output in a * string. The shell used is that specified by the 'shell' option. diff --git a/common/content/liberator.js b/common/content/liberator.js index 2e009250..3c6cbe9c 100644 --- a/common/content/liberator.js +++ b/common/content/liberator.js @@ -26,7 +26,6 @@ the provisions above, a recipient may use your version of this file under the terms of any one of the MPL, the GPL or the LGPL. }}} ***** END LICENSE BLOCK *****/ - /** @scope modules */ Cu.import("resource://gre/modules/XPCOMUtils.jsm", modules); @@ -87,8 +86,8 @@ const liberator = (function () //{{{ } } - // initially hide all GUI, it is later restored unless the user has :set go= or something - // similar in his config + // initially hide all GUI elements, they are later restored unless the user + // has :set go= or something similar in his config function hideGUI() { let guioptions = config.guioptions; @@ -108,7 +107,6 @@ const liberator = (function () //{{{ function getPlatformFeature() { let platform = navigator.platform; - return /^Mac/.test(platform) ? "MacUnix" : platform == "Win32" ? "Win32" : "Unix"; } @@ -153,7 +151,7 @@ const liberator = (function () //{{{ ////////////////////// OPTIONS ///////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////{{{ - // 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 Liberator extensions registerObserver("load_options", function () { options.add(["errorbells", "eb"], @@ -644,7 +642,10 @@ const liberator = (function () //{{{ modules: modules, - /** @property {number} The current main mode. */ + /** + * @property {number} The current main mode. + * @see modes#mainModes + */ get mode() modes.main, set mode(value) modes.main = value, @@ -661,14 +662,13 @@ const liberator = (function () //{{{ forceNewTab: false, - // these VERSION and DATE tokens are replaced by the Makefile - /** @property {string} The liberator application version string. */ - version: "###VERSION### (created: ###DATE###)", + /** @property {string} The Liberator version string. */ + version: "###VERSION### (created: ###DATE###)", // these VERSION and DATE tokens are replaced by the Makefile // NOTE: services.get("profile").selectedProfile.name doesn't return // what you might expect. It returns the last _actively_ selected - // profile (i.e. via the Profile Manager or -p option) rather than the - // current one. These will differ if the current process was run + // profile (i.e. via the Profile Manager or -P option) rather than the + // current profile. These will differ if the current process was run // without explicitly selecting a profile. /** @property {string} The name of the current user profile. */ profileName: services.get("directory").get("ProfD", Ci.nsIFile).leafName.replace(/^.+?\./, ""), @@ -688,7 +688,7 @@ const liberator = (function () //{{{ rcFile: null, /** @property An Ex command to run before any initialization is performed. */ preCommand: null, - /** @property An Ex command to run after all initialization is performed. */ + /** @property An Ex command to run after all initialization has been performed. */ postCommand: null }, @@ -758,15 +758,39 @@ const liberator = (function () //{{{ return false; // so you can do: if (...) return liberator.beep(); }, + /** + * Creates a new thread. + */ newThread: function () services.get("threadManager").newThread(0), + /** + * Calls a function asynchronously on a new thread. + * + * @param {nsIThread} thread The thread to call the function on. If no + * thread is specified a new one is created. + * @optional + * @param {Object} self The 'this' object used when executing the + * function. + * @param {function} func The function to execute. + * + */ callAsync: function (thread, self, func) { thread = thread || services.get("threadManager").newThread(0); thread.dispatch(new Runnable(self, func, Array.slice(arguments, 3)), thread.DISPATCH_NORMAL); }, - // be sure to call GUI related methods like alert() or dump() ONLY in the main thread + /** + * Calls a function synchronously on a new thread. + * + * NOTE: Be sure to call GUI related methods like alert() or dump() + * ONLY in the main thread. + * + * @param {nsIThread} thread The thread to call the function on. If no + * thread is specified a new one is created. + * @optional + * @param {function} func The function to execute. + */ callFunctionInThread: function (thread, func) { thread = thread || services.get("threadManager").newThread(0); @@ -775,11 +799,13 @@ const liberator = (function () //{{{ thread.dispatch(new Runnable(null, func, Array.slice(arguments, 2)), thread.DISPATCH_SYNC); }, - // NOTE: "browser.dom.window.dump.enabled" preference needs to be set /** * Prints a message to the console. If <b>msg</b> is an object it is * pretty printed. * + * NOTE: the "browser.dom.window.dump.enabled" preference needs to be + * set. + * * @param {string|Object} msg The message to print. */ dump: function (msg) @@ -805,12 +831,26 @@ const liberator = (function () //{{{ liberator.dump((msg || "Stack") + "\n" + stack); }, + /** + * Outputs a plain message to the command line. + * + * @param {string} str The message to output. + * @param {number} flags These control the multiline message behaviour. + * See {@link CommandLine#echo}. + */ echo: function (str, flags) { commandline.echo(str, commandline.HL_NORMAL, flags); }, // TODO: Vim replaces unprintable characters in echoerr/echomsg + /** + * Outputs an error message to the command line. + * + * @param {string} str The message to output. + * @param {number} flags These control the multiline message behaviour. + * See {@link CommandLine#echo}. + */ echoerr: function (str, flags) { flags |= commandline.APPEND_TO_MESSAGES; @@ -827,6 +867,16 @@ const liberator = (function () //{{{ }, // TODO: add proper level constants + /** + * Outputs an information message to the command line. + * + * @param {string} str The message to output. + * @param {number} verbosity The messages log level (0 - 15). Only + * messages with verbosity less than or equal to the value of the + * 'verbosity' option will be output. + * @param {number} flags These control the multiline message behaviour. + * See {@link CommandLine#echo}. + */ echomsg: function (str, verbosity, flags) { // TODO: is there a reason for this? --djk @@ -851,6 +901,15 @@ const liberator = (function () //{{{ commandline.echo(str, commandline.HL_INFOMSG, flags); }, + /** + * Loads and executes the script referenced by <b>uri</b> in the scope + * of the <b>context</b> object. + * + * @param {string} uri The URI of the script to load. Should be a local + * chrome:, file:, or resource: URL. + * @param {Object} context The context object into which the script + * should be loaded. + */ loadScript: function (uri, context) { services.get("subscriptLoader").loadSubScript(uri, context); @@ -978,7 +1037,7 @@ const liberator = (function () //{{{ }, /** - * Focus the content window. + * Focuses the content window. * * @param {boolean} clearFocusedElement Remove focus from any focused * element. @@ -1014,16 +1073,33 @@ const liberator = (function () //{{{ elem.focus(); }, - // does this liberator extension have a certain feature? + /** + * Returns whether this Liberator extension supports <b>feature</b>. + * + * @param {string} feature The feature name. + * @returns {boolean} + */ has: function (feature) config.features.indexOf(feature) >= 0, + /** + * Returns whether the host application has the specified extension + * installed. + * + * @param {string} name The extension name. + * @returns {boolean} + */ hasExtension: function (name) { let extensions = services.get("extensionManager").getItemList(Ci.nsIUpdateItem.TYPE_EXTENSION, {}); - return extensions.some(function (e) e.name == name); }, + /** + * Returns the URL of the specified help <b>topic</b> if it exists. + * + * @param {string} topic The help topic to lookup. + * @returns {string} + */ findHelp: function (topic) { let items = completion.runCompleter("help", topic); @@ -1041,9 +1117,17 @@ const liberator = (function () //{{{ if (partialMatch) return format(partialMatch); - return null; + else + return null; }, + /** + * Opens the help page containing the specified <b>topic</b> if it + * exists. + * + * @param {string} topic The help topic to open. + * @returns {string} + */ help: function (topic) { let where = (options["newtab"] && options.get("newtab").has("all", "help")) @@ -1069,6 +1153,11 @@ const liberator = (function () //{{{ content.postMessage("fragmentChange", "*"); }, + /** + * The map of global variables. + * + * These are set and accessed with the "g:" prefix. + */ globalVariables: {}, loadModule: function (name, func) { loadModule(name, func); }, @@ -1239,7 +1328,14 @@ const liberator = (function () //{{{ // v.plugins.onEvent = <func> function triggered, on keypresses (unless <esc>) (see events.js) plugins: plugins, - // quit liberator, no matter how many tabs/windows are open + /** + * Quit the host application, no matter how many tabs/windows are open. + * + * @param {boolean} saveSession If true the current session will be + * saved and restored when the host application is restarted. + * @param {boolean} force Forcibly quit irrespective of whether all + * windows could be closed individually. + */ quit: function (saveSession, force) { // TODO: Use safeSetPref? @@ -1254,10 +1350,17 @@ const liberator = (function () //{{{ window.goQuitApplication(); }, + /** + * Reports an error to both the console and the host application's + * Error Console. + * + * @param {Object} error The error object. + */ reportError: function (error) { if (Cu.reportError) Cu.reportError(error); + try { let obj = { @@ -1276,7 +1379,7 @@ const liberator = (function () //{{{ }, /** - * Restart the Liberator host application. + * Restart the host application. */ restart: function () { @@ -1302,7 +1405,16 @@ const liberator = (function () //{{{ services.get("appStartup").quit(Ci.nsIAppStartup.eRestart | Ci.nsIAppStartup.eAttemptQuit); }, - parseCommandLine: function (commandline) + /** + * Parses a Liberator command-line string i.e. the value of the + * -liberator command-line option. + * + * @param {string} cmdline The string to parse for command-line + * options. + * @returns {Object} + * @see Commands#parseArgs + */ + parseCommandLine: function (cmdline) { const options = [ [["+u"], commands.OPTIONS_STRING], @@ -1310,10 +1422,9 @@ const liberator = (function () //{{{ [["++cmd"], commands.OPTIONS_STRING], [["+c"], commands.OPTIONS_STRING] ]; - return commands.parseArgs(commandline, options, "*"); + return commands.parseArgs(cmdline, options, "*"); }, - // TODO: move to {muttator,vimperator,...}.js // this function is called when the chrome is ready startup: function () { diff --git a/common/content/style.js b/common/content/style.js index 0b4c1bca..b6afc8b7 100644 --- a/common/content/style.js +++ b/common/content/style.js @@ -200,7 +200,7 @@ function Highlights(name, store) this.selector = function (class) { let [, hl, rest] = class.match(/^(\w*)(.*)/); - return "[liberator|highlight~=" + hl + "]" + rest + return "[liberator|highlight~=" + hl + "]" + rest; }; /** diff --git a/common/content/ui.js b/common/content/ui.js index e7b1acf2..4f2c3601 100644 --- a/common/content/ui.js +++ b/common/content/ui.js @@ -812,7 +812,6 @@ function CommandLine() //{{{ validator: Option.validateCompleter }); - // TODO: these belong in ui.js options.add(["complete", "cpt"], "Items which are completed at the :[tab]open prompt", "charlist", "slf", @@ -1072,7 +1071,7 @@ function CommandLine() //{{{ * Open the command line. The main mode is set to * COMMAND_LINE, the extended mode to <b>extendedMode</b>. * Further, callbacks defined for <b>extendedMode</b> are - * triggered as appropriate (see {@link Liberator#registerCallback}). + * triggered as appropriate (see {@link liberator#registerCallback}). * * @param {string} prompt * @param {string} cmd diff --git a/common/content/util.js b/common/content/util.js index 5659532a..50e83f77 100644 --- a/common/content/util.js +++ b/common/content/util.js @@ -179,9 +179,9 @@ const util = { //{{{ }, /** - * Split a string on literal occurances of a marker. + * Split a string on literal occurrences of a marker. * - * Specifically this ignores occurences preceded by a backslash, or + * Specifically this ignores occurrences preceded by a backslash, or * contained within 'single' or "double" quotes. * * It assumes backslash escaping on strings, and will thus not count quotes @@ -703,6 +703,7 @@ const util = { //{{{ } }; //}}} +// TODO: Why don't we just push all util.BuiltinType up into modules? --djk /** * Array utility methods. */ diff --git a/muttator/content/config.js b/muttator/content/config.js index 13bc91f9..fd150ef6 100644 --- a/muttator/content/config.js +++ b/muttator/content/config.js @@ -30,6 +30,7 @@ const config = { //{{{ /*** required options, no checks done if they really exist, so be careful ***/ name: "Muttator", hostApplication: "Thunderbird", // TODO: can this be found out otherwise? gBrandBundle.getString("brandShortName"); + // Yes, but it will be localized unlike all other strings. So, it's best left until we i18n liberator. --djk get mainWindowID() this.isComposeWindow ? "msgcomposeWindow" : "messengerWindow", /*** optional options, there are checked for existence and a fallback provided ***/ diff --git a/vimperator/TODO b/vimperator/TODO index 1fd7fe89..f88688bd 100644 --- a/vimperator/TODO +++ b/vimperator/TODO @@ -6,6 +6,7 @@ ARCHITECTURE: - I made a quick attempt at parameterizing it using attributes but it breaks Asciidoc formatting in certain unpredictable (to me at least) contexts. *sigh* --djk +- decide on how to document Arrays in our jsdoc(ish) documentation. BUGS: - add window resize support to hints diff --git a/vimperator/content/config.js b/vimperator/content/config.js index a4de986b..9a0e2dc1 100644 --- a/vimperator/content/config.js +++ b/vimperator/content/config.js @@ -383,7 +383,6 @@ const config = { //{{{ }, { argCount: "0" }); - // TODO: move sidebar commands to ui.js? commands.add(["sbcl[ose]"], "Close the sidebar window", function () |