diff --git a/common/content/hints.js b/common/content/hints.js
index 6c9692db..2a76dd3f 100644
--- a/common/content/hints.js
+++ b/common/content/hints.js
@@ -638,8 +638,8 @@ function Hints() //{{{
* @param {boolean} allowWordOverleaping Whether to allow non-contiguous
* words to match.
*
- * @return {function(String):bool} A function that will filter only
- * hints that match as above.
+ * @return {function(String):boolean} A function that will filter only
+ * hints that match as above.
*/
function wordStartsWithMatcher(hintString, allowWordOverleaping) //{{{
{
@@ -897,14 +897,16 @@ function Hints() //{{{
return {
/**
- * Create a new hint mode
+ * Creates a new hint mode.
*
* @param {String} mode The letter that identifies this mode.
- * @param {String} description The description to display to the user about this mode.
- * @param {function(Node)} callback 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 default returns
- * options.hinttags)
+ * @param {String} description The description to display to the user
+ * about this mode.
+ * @param {function(Node)} callback 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
+ * default returns options.hinttags).
*/
addMode: function (mode)
{
@@ -912,11 +914,11 @@ function Hints() //{{{
},
/**
- * Update the display of hints.
+ * Updates the display of hints.
*
* @param {String} minor Which hint mode to use.
* @param {String} filter The filter to use.
- * @param {Object} win The window in which we are showing hints
+ * @param {Object} win The window in which we are showing hints.
*/
show: function (minor, filter, win)
{
@@ -968,7 +970,7 @@ function Hints() //{{{
},
/**
- * Handle an event
+ * Handle an event.
*
* @param {Event} event The event to handle.
*/
diff --git a/common/content/tabs.js b/common/content/tabs.js
index c3d9f059..61c96ced 100644
--- a/common/content/tabs.js
+++ b/common/content/tabs.js
@@ -30,6 +30,9 @@ the terms of any one of the MPL, the GPL or the LGPL.
// TODO: many methods do not work with Thunderbird correctly yet
+/**
+ * @instance tabs
+ */
function Tabs() //{{{
{
////////////////////////////////////////////////////////////////////////////////
@@ -676,8 +679,16 @@ function Tabs() //{{{
return {
+ /**
+ * @property {Object} The previously accessed tab or null if no tab
+ * other than the current one has been accessed.
+ */
get alternate() alternates[1],
+ /**
+ * @property {Iterator(Object)} A genenerator that returns all browsers
+ * in the current window.
+ */
get browsers()
{
let browsers = getBrowser().browsers;
@@ -685,10 +696,13 @@ function Tabs() //{{{
yield [i, browsers[i]];
},
- get tabsBound() {
- return Boolean(styles.get(true, "tab-binding"))
- },
- set tabsBound(val) {
+ /**
+ * @property {boolean} Whether the tab numbering XBL binding has been
+ * applied.
+ */
+ get tabsBound() Boolean(styles.get(true, "tab-binding")),
+ set tabsBound(val)
+ {
let fragment = liberator.has("MacUnix") ? "tab-mac" : "tab";
if (!val)
styles.removeSheet(true, "tab-binding");
@@ -699,8 +713,14 @@ function Tabs() //{{{
".tabbrowser-tab[busy] > .tab-icon > .tab-icon-image { list-style-image: url('chrome://global/skin/icons/loading_16.png') !important; }");
},
+ /**
+ * @property {number} The number of tabs in the current window.
+ */
get count() getBrowser().mTabs.length,
+ /**
+ * @property {Object} The local options store for the current tab.
+ */
get options()
{
let store = this.localStore;
@@ -709,6 +729,15 @@ function Tabs() //{{{
return store.options;
},
+ /**
+ * Returns the local state store for the tab at the specified
+ * tabIndex. If tabIndex is not specified then the
+ * current tab is used.
+ *
+ * @param {number} tabIndex
+ * @returns {Object}
+ */
+ // FIXME: why not a tab arg? Why this and the property?
getLocalStore: function (tabIndex)
{
let tab = this.getTab(tabIndex);
@@ -717,8 +746,15 @@ function Tabs() //{{{
return tab.liberatorStore;
},
+ /**
+ * @property {Object} The local state store for the currently selected
+ * tab.
+ */
get localStore() this.getLocalStore(),
+ /**
+ * @property {Object} The tab browser strip.
+ */
get tabStrip()
{
let tabStrip = null;
@@ -732,18 +768,40 @@ function Tabs() //{{{
return tabStrip;
},
- // @returns the index of the currently selected tab starting with 0
+ /**
+ * @property {Object[]} The array of closed tabs for the current
+ * session.
+ */
+ get closedTabs()
+ {
+ return services.get("json").decode(services.get("sessionStore").getClosedTabData(window));
+ },
+
+ /**
+ * Returns the index of tab or the index of the currently
+ * selected tab if tab is not specified. This is a 0-based
+ * index.
+ *
+ * @param {Object} tab A tab from the current tab list.
+ * @returns {number}
+ */
index: function (tab)
{
if (tab)
return Array.indexOf(getBrowser().mTabs, tab);
-
- return getBrowser().mTabContainer.selectedIndex;
+ else
+ return getBrowser().mTabContainer.selectedIndex;
},
// TODO: implement filter
- // @returns an array of tabs which match filter
- get: function (filter)
+ /**
+ * Returns an array of all tabs in the tab list.
+ *
+ * @returns {Object[]}
+ */
+ // FIXME: why not return the tab element?
+ // : unused? Remove me.
+ get: function ()
{
let buffers = [];
for (let [i, browser] in this.browsers)
@@ -756,6 +814,13 @@ function Tabs() //{{{
return buffers;
},
+ /**
+ * Returns the index of the tab containing content.
+ *
+ * @param {Object} content Either a content window or a content
+ * document.
+ */
+ // FIXME: Only called once...necessary?
getContentIndex: function (content)
{
for (let [i, browser] in this.browsers)
@@ -766,6 +831,14 @@ function Tabs() //{{{
return -1;
},
+ /**
+ * Returns the tab at the specified index or the currently
+ * selected tab if index is not specified. This is a 0-based
+ * index.
+ *
+ * @param {number} index The index of the tab required.
+ * @returns {Object}
+ */
getTab: function (index)
{
if (index != undefined)
@@ -774,26 +847,44 @@ function Tabs() //{{{
return getBrowser().mCurrentTab;
},
- get closedTabs()
- {
- return services.get("json").decode(services.get("sessionStore").getClosedTabData(window));
- },
-
+ /**
+ * Lists all tabs matching filter.
+ *
+ * @param {string} filter A filter matching a substring of the tab's
+ * document title or URL.
+ */
list: function (filter)
{
completion.listCompleter("buffer", filter);
},
- // wrap causes the movement to wrap around the start and end of the tab list
- // NOTE: position is a 0 based index
+ /**
+ * Moves a tab to a new position in the tab list.
+ *
+ * @param {Object} tab The tab to move.
+ * @param {string} spec See {@link indexFromSpec}.
+ * @param {boolean} wrap Whether an out of bounds spec causes
+ * the destination position to wrap around the start/end of the tab
+ * list.
+ */
move: function (tab, spec, wrap)
{
let index = indexFromSpec(spec, wrap);
getBrowser().moveTabTo(tab, index);
},
- // quitOnLastTab = 1: quit without saving session
- // quitOnLastTab = 2: quit and save session
+ /**
+ * Removes the specified tab from the tab list.
+ *
+ * @param {Object} tab
+ * @param {number} count
+ * @param {boolean} focusLeftTab Focus the tab to the left of the removed tab.
+ * @param {number} quitOnLastTab Whether to quit if the tab being
+ * deleted is the only tab in the tab list:
+ * 1 - quit without saving session
+ * 2 - quit and save session
+ */
+ // FIXME: what is quitOnLastTab {1,2} all about then, eh? --djk
remove: function (tab, count, focusLeftTab, quitOnLastTab)
{
let removeOrBlankTab = {
@@ -874,11 +965,24 @@ function Tabs() //{{{
}
},
+ /**
+ * Removes all tabs from the tab list except the specified tab.
+ *
+ * @param {Object} tab The tab to keep.
+ */
keepOnly: function (tab)
{
getBrowser().removeAllTabsBut(tab);
},
+ /**
+ * Selects the tab at the position specified by spec.
+ *
+ * @param {string} spec See {@link indexFromSpec}
+ * @param {boolean} wrap Whether an out of bounds spec causes
+ * the selection position to wrap around the start/end of the tab
+ * list.
+ */
select: function (spec, wrap)
{
let index = indexFromSpec(spec, wrap);
@@ -892,7 +996,7 @@ function Tabs() //{{{
},
/**
- * Reload the specified tab.
+ * Reloads the specified tab.
*
* @param {Object} tab The tab to reload.
* @param {boolean} bypassCache Whether to bypass the cache when
@@ -912,7 +1016,7 @@ function Tabs() //{{{
},
/**
- * Reload all tabs.
+ * Reloads all tabs.
*
* @param {boolean} bypassCache Whether to bypass the cache when
* reloading.
@@ -941,7 +1045,7 @@ function Tabs() //{{{
},
/**
- * Stop loading the specified tab.
+ * Stops loading the specified tab.
*
* @param {Object} tab The tab to stop loading.
*/
@@ -954,7 +1058,7 @@ function Tabs() //{{{
},
/**
- * Stop loading all tabs.
+ * Stops loading all tabs.
*/
stopAll: function ()
{
@@ -962,8 +1066,20 @@ function Tabs() //{{{
browser.stop();
},
- // "buffer" is a string which matches the URL or title of a buffer, if it
- // is null, the last used string is used again
+ /**
+ * Selects the tab containing the specified buffer.
+ *
+ * @param {string} buffer A string which matches the URL or title of a
+ * buffer, if it is null, the last used string is used again.
+ * @param {boolean} allowNonUnique Whether to select the first of
+ * multiple matches.
+ * @param {number} count If there are multiple matches select the
+ * count'th match.
+ * @param {boolean} reverse Whether to search the buffer list in
+ * reverse order.
+ *
+ */
+ // FIXME: help!
switchTo: function (buffer, allowNonUnique, count, reverse)
{
if (buffer == "")
@@ -1037,6 +1153,12 @@ function Tabs() //{{{
}
},
+ /**
+ * Clones the specified tab and append it to the tab list.
+ *
+ * @param {Object} tab The tab to clone.
+ * @param {boolean} activate Whether to select the newly cloned tab.
+ */
cloneTab: function (tab, activate)
{
let newTab = getBrowser().addTab();
@@ -1048,6 +1170,12 @@ function Tabs() //{{{
return newTab;
},
+ /**
+ * Detaches the specified tab and open it in a new window. If no
+ * tab is specified the currently selected tab is detached.
+ *
+ * @param {Object} tab The tab to detach.
+ */
detachTab: function (tab)
{
if (!tab)
@@ -1060,6 +1188,9 @@ function Tabs() //{{{
this.remove(tab, 1, false, 1);
},
+ /**
+ * Selects the alternate tab.
+ */
selectAlternateTab: function ()
{
if (tabs.alternate == null || tabs.getTab() == tabs.alternate)
@@ -1085,6 +1216,10 @@ function Tabs() //{{{
// tab that was selected when the session was created. As a result the
// alternate after a restart is often incorrectly tab 1 when there
// shouldn't be one yet.
+ /**
+ * Called on each TabSelect event to update the tab selection history.
+ * See (@link tabs.alternate).
+ */
updateSelectionHistory: function ()
{
alternates = [this.getTab(), alternates[0]];