Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2025-02-25 20:01:50 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Bug 1510561 - Part 2: Apply plugin:mozilla/valid-jsdoc to browser/components/places. r=Standard8

Browse Source 
Differential Revision: https://phabricator.services.mozilla.com/D158562
This commit is contained in:
trickypr 2022-10-13 10:55:28 +00:00
parent b536a0588c
commit 9e1b731098
26 changed files with 162 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
browser/components/places/.eslintrc.js
View File

@ -5,6 +5,8 @@
"use strict";
module.exports = {
extends: ["plugin:mozilla/valid-jsdoc"],
rules: {
"require-jsdoc": [
"error",
@ -18,23 +20,5 @@ module.exports = {
},
},
],
"valid-jsdoc": [
"error",
{
prefer: {
return: "returns",
},
preferType: {
Boolean: "boolean",
Number: "number",
String: "string",
Object: "object",
bool: "boolean",
},
requireParamDescription: false,
requireReturn: false,
requireReturnDescription: false,
},
],
},
};

2
browser/components/places/Interactions.sys.mjs
View File

@ -595,6 +595,7 @@ class InteractionsStore {
/**
* Tracks interactions replicating the unique index in the underlying schema.
* Interactions are keyed by url and then created_at.
*
* @type {Map<string, Map<number, InteractionInfo>>}
*/
#interactions = new Map();
@ -646,6 +647,7 @@ class InteractionsStore {
/**
* Synchronizes the pending interactions with the storage device.
*
* @returns {Promise} resolved when the pending data is on disk.
*/
async flush() {

12
browser/components/places/InteractionsBlocklist.sys.mjs
View File

@ -126,6 +126,7 @@ class _InteractionsBlocklist {
/**
* Only certain urls can be added as Interactions, either manually or
* automatically.
*
* @returns {Map} A Map keyed by protocol, for each protocol an object may
* define stricter requirements, like extension.
*/
@ -140,6 +141,7 @@ class _InteractionsBlocklist {
/**
* Whether to record interactions for a given URL.
* The rules are defined in InteractionsBlocklist.urlRequirements.
*
* @param {string|URL|nsIURI} url The URL to check.
* @returns {boolean} whether the url can be added to snapshots.
*/
@ -226,12 +228,11 @@ class _InteractionsBlocklist {
/**
* Adds a regex to HOST_BLOCKLIST. Since we can't parse the base host from
* the regex, we add it to a list of wildcard regexes. All URLs are checked
* against these wildcard regexes.
* against these wildcard regexes. Currently only exposed for tests and use in
* the console. In the future we could hook this up to a UI component.
*
* @param {string|RegExp} regexToAdd
* The regular expression to add to our blocklist.
* @note Currently only exposed for tests and use in the console. In the
* future we could hook this up to a UI component.
*/
addRegexToBlocklist(regexToAdd) {
let regex;
@ -254,12 +255,11 @@ class _InteractionsBlocklist {
/**
* Removes a regex from HOST_BLOCKLIST. If `regexToRemove` is not in the
* blocklist, this is a no-op.
* blocklist, this is a no-op. Currently only exposed for tests and use in the
* console. In the future we could hook this up to a UI component.
*
* @param {string|RegExp} regexToRemove
* The regular expression to add to our blocklist.
* @note Currently only exposed for tests and use in the console. In the
* future we could hook this up to a UI component.
*/
removeRegexFromBlocklist(regexToRemove) {
let regex;

48
browser/components/places/PlacesUIUtils.sys.mjs
View File

@ -52,6 +52,10 @@ let InternalFaviconLoader = {
* Actually cancel the request, and clear the timeout for cancelling it.
*
* @param {object} options
* @param {string} options.uri
* @param {number} options.innerWindowID
* @param {number} options.timerID
* @param {*} options.callback
* @param {string} reason
* The reason for cancelling the request.
*/
@ -125,6 +129,9 @@ let InternalFaviconLoader = {
* the chrome window in which we should look for this load
* @param {object} filterData ({innerWindowID, uri, callback})
* the data we should use to find this particular load to remove.
* @param {number} filterData.innerWindowID
* @param {string} filterData.uri
* @param {Function} filterData.callback
*
* @returns {object|null}
* the loadData object we removed, or null if we didn't find any.
@ -282,6 +289,7 @@ class BookmarkState {
/**
* Save edited title for the bookmark
*
* @param {string} title
*/
_titleChanged(title) {
@ -290,6 +298,7 @@ class BookmarkState {
/**
* Save edited location for the bookmark
*
* @param {string} location
*/
_locationChanged(location) {
@ -298,6 +307,7 @@ class BookmarkState {
/**
* Save edited tags for the bookmark
*
* @param {string} tags
* Comma separated list of tags
*/
@ -307,6 +317,7 @@ class BookmarkState {
/**
* Save edited keyword for the bookmark
*
* @param {string} keyword
*/
_keywordChanged(keyword) {
@ -315,6 +326,7 @@ class BookmarkState {
/**
* Save edited parentGuid for the bookmark
*
* @param {string} parentGuid
*/
_parentGuidChanged(parentGuid) {
@ -445,7 +457,7 @@ export var PlacesUIUtils = {
* key for looking up the localized string in the bundle
* @param {number} aNumber
* Number based on which the final localized form is looked up
* @param {array} aParams
* @param {Array} aParams
* Array whose items will substitute #1, #2,... #n parameters
* in the string.
*
@ -581,9 +593,9 @@ export var PlacesUIUtils = {
* Bookmarks one or more pages. If there is more than one, this will create
* the bookmarks in a new folder.
*
* @param {array.<nsIURI>} URIList
* @param {Array.<nsIURI>} URIList
* The list of URIs to bookmark.
* @param {array.<string>} [hiddenRows]
* @param {Array.<string>} [hiddenRows]
* An array of rows to be hidden.
* @param {DOMWindow} [win]
* The window to use as the parent to display the bookmark dialog.
@ -608,6 +620,7 @@ export var PlacesUIUtils = {
/**
* set and fetch a favicon. Can only be used from the parent process.
*
* @param {object} browser
* The XUL browser element for which we're fetching a favicon.
* @param {Principal} principal
@ -644,6 +657,7 @@ export var PlacesUIUtils = {
/**
* Returns the closet ancestor places view for the given DOM node
*
* @param {DOMNode} aNode
* a DOM node
* @returns {DOMNode} the closest ancestor places view if exists, null otherwsie.
@ -838,6 +852,7 @@ export var PlacesUIUtils = {
/**
* Allows opening of javascript/data URI only if the given node is
* bookmarked (see bug 224521).
*
* @param {object} aURINode
* a URI node
* @param {DOMWindow} aWindow
@ -936,7 +951,7 @@ export var PlacesUIUtils = {
},
/**
* @param {array<object>} aItemsToOpen
* @param {Array<object>} aItemsToOpen
* needs to be an array of objects of the form:
* {uri: string, isBookmark: boolean}
* @param {object} aEvent
@ -1007,7 +1022,7 @@ export var PlacesUIUtils = {
* Loads a selected node's or nodes' URLs in tabs,
* warning the user when lots of URLs are being opened
*
* @param {object|array} nodeOrNodes
* @param {object | Array} nodeOrNodes
* Contains the node or nodes that we're opening in tabs
* @param {event} event
* The DOM mouse/key event with modifier keys set that track the
@ -1042,6 +1057,7 @@ export var PlacesUIUtils = {
* Loads the node's URL in the appropriate tab or window given the
* user's preference specified by modifier keys tracked by a
* DOM mouse/key event.
*
* @param {object} aNode
* An uri result node.
* @param {object} aEvent
@ -1118,11 +1134,11 @@ export var PlacesUIUtils = {
/**
* Helper for guessing scheme from an url string.
* Used to avoid nsIURI overhead in frequently called UI functions.
* Used to avoid nsIURI overhead in frequently called UI functions. This is not
* supposed be perfect, so use it only for UI purposes.
*
* @param {string} href The url to guess the scheme from.
* @returns {string} guessed scheme for this url string.
* @note this is not supposed be perfect, so use it only for UI purposes.
*/
guessUrlSchemeForUI(href) {
return href.substr(0, href.indexOf(":"));
@ -1254,11 +1270,10 @@ export var PlacesUIUtils = {
/**
* This function wraps potentially large places transaction operations
* with batch notifications to the result node, hence switching the views
* to batch mode.
* to batch mode. If resultNode is not supplied, the function will
* pass-through to functionToWrap.
*
* @param {nsINavHistoryResult} resultNode The result node to turn on batching.
* @note If resultNode is not supplied, the function will pass-through to
* functionToWrap.
* @param {number} itemsBeingChanged The count of items being changed. If the
* count is lower than a threshold, then
* batching won't be set.
@ -1287,12 +1302,12 @@ export var PlacesUIUtils = {
* Processes a set of transfer items that have been dropped or pasted.
* Batching will be applied where necessary.
*
* @param {array} items A list of unwrapped nodes to process.
* @param {Array} items A list of unwrapped nodes to process.
* @param {object} insertionPoint The requested point for insertion.
* @param {boolean} doCopy Set to true to copy the items, false will move them
* if possible.
* @param {object} view The view that should be used for batching.
* @returns {array} Returns an empty array when the insertion point is a tag, else
* @returns {Array} Returns an empty array when the insertion point is a tag, else
* returns an array of copied or moved guids.
*/
async handleTransferItems(items, insertionPoint, doCopy, view) {
@ -1451,7 +1466,7 @@ export var PlacesUIUtils = {
* If the user does not have a persisted value for the toolbar's
* "collapsed" attribute, try to determine whether it's customized.
*
* @param {Boolean} aForceVisible Set to true to ignore if the user had
* @param {boolean} aForceVisible Set to true to ignore if the user had
* previously collapsed the toolbar manually.
*/
NUM_TOOLBAR_BOOKMARKS_TO_UNHIDE: 3,
@ -1803,12 +1818,13 @@ export var PlacesUIUtils = {
},
/**
* Tries to initiate a speculative connection to a given url.
* Tries to initiate a speculative connection to a given url. This is not
* infallible, if a speculative connection cannot be initialized, it will be a
* no-op.
*
* @param {nsIURI|URL|string} url entity to initiate
* a speculative connection for.
* @param {window} window the window from where the connection is initialized.
* @note This is not infallible, if a speculative connection cannot be
* initialized, it will be a no-op.
*/
setupSpeculativeConnection(url, window) {
if (

1
browser/components/places/SnapshotGroups.sys.mjs
View File

@ -580,6 +580,7 @@ export const SnapshotGroups = new (class SnapshotGroups {
/**
* Prefetch a screenshot for the oldest snapshot in the group.
*
* @param {number} id
* The id of the group to add the urls to.
*/

1
browser/components/places/SnapshotScorer.sys.mjs
View File

@ -112,6 +112,7 @@ export const SnapshotScorer = new (class SnapshotScorer {
/**
* Maintains the current score for each seen snapshot.
*
* @type {Map<string, SnapshotScore>}
*/
let combined = new Map();

16
browser/components/places/SnapshotSelector.sys.mjs
View File

@ -48,7 +48,7 @@ XPCOMUtils.defineLazyGetter(lazy, "logConsole", function() {
* The page the snapshots are for.
* @property {PageDataCollector.DATA_TYPE | undefined} type
* The type of snapshots desired.
* @property {function} getCurrentSessionUrls
* @property {Function} getCurrentSessionUrls
* A function that returns a Set containing the urls for the current session.
*/
@ -124,7 +124,7 @@ export class SnapshotSelector extends EventEmitter {
* Whether adult sites should be filtered from the snapshots.
* @param {object | undefined} [options.sourceWeights]
* Overrides for the weights of different recommendation sources.
* @param {function} [options.getCurrentSessionUrls]
* @param {Function} [options.getCurrentSessionUrls]
* A function that returns a Set containing the urls for the current session.
*/
constructor({
@ -310,15 +310,17 @@ export class SnapshotSelector extends EventEmitter {
/**
* Update context details and start a rebuild.
* Undefined properties are ignored, thus pass null to nullify a property.
* @param {string} [url]
*
* @param {object} context
* @param {string} [context.url]
* The url of the current context.
* @param {number} [time]
* @param {number} [context.time]
* The time, in milliseconds since the Unix epoch.
* @param {PageDataSchema.DATA_TYPE} [type]
* @param {PageDataSchema.DATA_TYPE} [context.type]
* The type of snapshots for this selector.
* @param {number} [sessionStartTime]
* @param {number} [context.sessionStartTime]
* The start time of the session, in milliseconds since the Unix epoch.
* @param {string} [rebuildImmediately] (default: false)
* @param {string} [context.rebuildImmediately] (default: false)
* Whether to rebuild immediately instead of waiting some delay. Useful on
* startup.
*/

21
browser/components/places/Snapshots.sys.mjs
View File

@ -177,7 +177,7 @@ XPCOMUtils.defineLazyPreferenceGetter(
* Whether the user created the snapshot and if they did, through what action.
* @property {Map<type, data>} pageData
* Collection of PageData by type. See PageDataService.jsm
* @property {Number} overlappingVisitScore
* @property {number} overlappingVisitScore
* Calculated score based on overlapping visits to the context url. In the range [0.0, 1.0]
* @property {number} [relevancyScore]
* The relevancy score associated with the snapshot.
@ -235,7 +235,8 @@ export const Snapshots = new (class Snapshots {
/**
* This is called by PageThumbs to see what thumbnails should be kept alive.
* Currently, the last 100 snapshots are kept alive.
* @param {function} callback
*
* @param {Function} callback
*/
async filterForThumbnailExpiration(callback) {
let snapshots = await this.query();
@ -248,6 +249,7 @@ export const Snapshots = new (class Snapshots {
/**
* Fetches page data for the given urls and stores it with snapshots.
*
* @param {Array<Objects>} urls Array of {placeId, url} tuples.
*/
async #addPageData(urls) {
@ -365,6 +367,7 @@ export const Snapshots = new (class Snapshots {
/**
* Returns the url up until, but not including, any hash mark identified fragments
* For example, given http://www.example.org/foo.html#bar, this function will return http://www.example.org/foo.html
*
* @param {string} url
* The url associated with the snapshot.
* @returns {string}
@ -595,7 +598,7 @@ export const Snapshots = new (class Snapshots {
* Restrict the snapshots to those with a particular type of page data available.
* @param {number} [options.group]
* Restrict the snapshots to those within a particular group.
* @param {boolean} [includeSnapshotsInUserManagedGroups]
* @param {boolean} [options.includeSnapshotsInUserManagedGroups]
* Whether snapshots that are in a user managed group should be included.
* Snapshots that are part of multiple groups are excluded even if only one
* of the groups is user managed.
@ -926,17 +929,18 @@ export const Snapshots = new (class Snapshots {
/**
* Calculate score for a timeOfDay entry, based on the number of interactions.
* This function is useful for testing scores.
*
* @param {number} interactions
* @param {object} options Options object.
* @param {number} options.interactions
* The number of interactions with the page.
* @param {object} context
* @param {object} options.context
* The selection context.
* @param {number} min
* @param {number} options.min
* The minimum number of interactions during snapshot_timeofday_limit_days.
* @param {number} max
* @param {number} options.max
* The maximum number of interactions during snapshot_timeofday_limit_days.
* @returns {float} Calculated score for the page.
* @note This function is useful for testing scores.
*/
timeOfDayScore({ interactions, context, min, max }) {
// Assign score 1.0 to the pages having more than max / 2 interactions,
@ -1030,6 +1034,7 @@ export const Snapshots = new (class Snapshots {
* returned comes from the following priority:
* 1) meta data page image
* 2) thumbnail of the page
*
* @param {Snapshot} snapshot
*
* @returns {string?}

1
browser/components/places/content/browserPlacesViews.js
View File

@ -723,6 +723,7 @@ PlacesViewBase.prototype = {
/**
* Adds an "Open All in Tabs" menuitem to the bottom of the popup.
*
* @param {object} aPopup
* a Places popup.
*/

46
browser/components/places/content/controller.js
View File

@ -15,21 +15,22 @@ ChromeUtils.defineESModuleGetters(this, {
/**
* Represents an insertion point within a container where we can insert
* items.
* @param {object} an object containing the following properties:
* - parentId
*
* @param {object} options an object containing the following properties:
* @param {number} options.parentId
* The identifier of the parent container
* - parentGuid
* @param {*} options.parentGuid
* The unique identifier of the parent container
* - index
* @param {number} [options.index]
* The index within the container where to insert, defaults to appending
* - orientation
* @param {number} [options.orientation]
* The orientation of the insertion. NOTE: the adjustments to the
* insertion point to accommodate the orientation should be done by
* the person who constructs the IP, not the user. The orientation
* is provided for informational purposes only! Defaults to DROP_ON.
* - tagName
* @param {string} [options.tagName]
* The tag name if this IP is set to a tag, null otherwise.
* - dropNearNode
* @param {*} [options.dropNearNode]
* When defined index will be calculated based on this node
*/
function PlacesInsertionPoint({
@ -380,7 +381,7 @@ PlacesController.prototype = {
* "separator" node is a separator line
* "host" node is a host
*
* @returns {array} an array of objects corresponding the selected nodes. Each
* @returns {Array} an array of objects corresponding the selected nodes. Each
* object has each of the properties above set if its corresponding
* node matches the rule. In addition, the annotations names for each
* node are set on its corresponding object as properties.
@ -435,6 +436,7 @@ PlacesController.prototype = {
/**
* Determines if a context-menu item should be shown
*
* @param {object} aMenuItem
* the context menu item
* @param {object} aMetaData
@ -776,9 +778,10 @@ PlacesController.prototype = {
* Walk the list of folders we're removing in this delete operation, and
* see if the selected node specified is already implicitly being removed
* because it is a child of that folder.
*
* @param {object} node
* Node to check for containment.
* @param {array} pastFolders
* @param {Array} pastFolders
* List of folders the calling function has already traversed
* @returns {boolean} true if the node should be skipped, false otherwise.
*/
@ -812,11 +815,12 @@ PlacesController.prototype = {
/**
* Creates a set of transactions for the removal of a range of items.
* A range is an array of adjacent nodes in a view.
* @param {array} range
*
* @param {Array} range
* An array of nodes to remove. Should all be adjacent.
* @param {array} transactions
* @param {Array} transactions
* An array of transactions (returned)
* @param {array} [removedFolders]
* @param {Array} [removedFolders]
* An array of folder nodes that have already been removed.
* @returns {number} The total number of items affected.
*/
@ -929,9 +933,8 @@ PlacesController.prototype = {
},
/**
* Removes the set of selected ranges from history, asynchronously.
*
* @note history deletes are not undoable.
* Removes the set of selected ranges from history, asynchronously. History
* deletes are not undoable.
*/
async _removeRowsFromHistory() {
let nodes = this._view.selectedNodes;
@ -955,11 +958,11 @@ PlacesController.prototype = {
},
/**
* Removes history visits for an history container node.
* Removes history visits for an history container node. History deletes are
* not undoable.
*
* @param {object} aContainerNode
* The container node to remove.
*
* @note history deletes are not undoable.
*/
async _removeHistoryContainer(aContainerNode) {
if (PlacesUtils.nodeIsHost(aContainerNode)) {
@ -1020,6 +1023,7 @@ PlacesController.prototype = {
/**
* Fills a DataTransfer object with the content of the selection that can be
* dropped elsewhere.
*
* @param {object} aEvent
* The dragstart event.
*/
@ -1293,6 +1297,7 @@ PlacesController.prototype = {
/**
* Checks if we can insert into a container.
*
* @param {object} container
* The container were we are want to drop
* @returns {boolean}
@ -1448,6 +1453,7 @@ var PlacesControllerDragHelper = {
* Determines if the mouse is currently being dragged over a child node of
* this menu. This is necessary so that the menu doesn't close while the
* mouse is dragging over one of its submenus
*
* @param {object} node
* The container node
* @returns {boolean} true if the user is dragging over a node within the hierarchy of
@ -1465,7 +1471,7 @@ var PlacesControllerDragHelper = {
},
/**
* @returns{object|null} The current active drag session. Returns null if there is none.
* @returns {object|null} The current active drag session. Returns null if there is none.
*/
getSession: function PCDH__getSession() {
return this.dragService.getCurrentSession();
@ -1473,6 +1479,7 @@ var PlacesControllerDragHelper = {
/**
* Extract the first accepted flavor from a list of flavors.
*
* @param {DOMStringList} aFlavors
* The flavors list.
* @returns {string}
@ -1497,6 +1504,7 @@ var PlacesControllerDragHelper = {
/**
* Determines whether or not the data currently being dragged can be dropped
* on a places view.
*
* @param {object} ip
* The insertion point where the items should be dropped.
* @param {object} dt

2
browser/components/places/content/editBookmark.js
View File

@ -247,7 +247,7 @@ var gEditItemOverlay = {
* @param {nsIURI[]} [aInfo.uris]
* If aInfo.node is not specified, this must be specified.
* An array of uris for bulk tagging.
* @param {string[]} [hiddenRows]
* @param {string[]} [aInfo.hiddenRows]
* List of rows to be hidden regardless of the item edited. Possible values:
* "title", "location", "keyword", "folderPicker".
*/

2
browser/components/places/content/instantEditBookmark.js
View File

@ -238,7 +238,7 @@ var gEditItemOverlay = {
* @param {nsIURI[]} [aInfo.uris]
* If aInfo.node is not specified, this must be specified.
* An array of uris for bulk tagging.
* @param {string[]} [hiddenRows]
* @param {string[]} [aInfo.hiddenRows]
* List of rows to be hidden regardless of the item edited. Possible values:
* "title", "location", "keyword", "folderPicker".
*/

3
browser/components/places/content/places-tree.js
View File

@ -164,6 +164,7 @@
}
/**
* overriding
*
* @param {object} val
*/
set view(val) {
@ -676,7 +677,7 @@
* each given item guid. It will open any folder nodes that it needs
* to in order to show the selected items.
*
* @param {array} aGuids
* @param {Array} aGuids
* Guids to select.
* @param {boolean} aOpenContainers
* Whether or not to open containers.

15
browser/components/places/content/places.js
View File

@ -107,7 +107,7 @@ var PlacesOrganizer = {
* Opens a given hierarchy in the left pane, stopping at the last reachable
* container. Note: item ids should be considered deprecated.
*
* @param {array|string|number} aHierarchy
* @param {Array | string | number} aHierarchy
* A single container or an array of containers, sorted from
* the outmost to the innermost in the hierarchy. Each
* container may be either an item id, a Places URI string,
@ -329,6 +329,7 @@ var PlacesOrganizer = {
/**
* Called when a place folder is selected in the left pane.
*
* @param resetSearchBox
* true if the search box should also be reset, false otherwise.
* The search box should be reset when a new folder in the left
@ -378,6 +379,7 @@ var PlacesOrganizer = {
/**
* Sets the search scope based on aNode's properties.
*
* @param {object} aNode
* the node to set up scope from
*/
@ -401,6 +403,7 @@ var PlacesOrganizer = {
* Handle clicks on the places list.
* Single Left click, right click or modified click do not result in any
* special action, since they're related to selection.
*
* @param {object} aEvent
* The mouse event.
*/
@ -440,6 +443,7 @@ var PlacesOrganizer = {
/**
* Handle openFlatContainer events.
*
* @param {object} aContainer
* The node the event was dispatched on.
*/
@ -840,6 +844,7 @@ var PlacesSearchBox = {
* Run a search for the specified text, over the collection specified by
* the dropdown arrow. The default is all bookmarks, but can be
* localized to the active collection.
*
* @param {string} filterString
* The text to search for.
*/
@ -916,6 +921,7 @@ var PlacesSearchBox = {
/**
* Updates the display with the title of the current collection.
*
* @param {string} aTitle
* The title of the current collection.
*/
@ -986,6 +992,7 @@ var PlacesQueryBuilder = {
* in that case, when the user does begin a search aScope will be used (see
* PSB_search()). If there is an active search, it's performed again to
* update the content tree.
*
* @param {string} aScope
* The search scope: "bookmarks", "collection", "downloads" or
* "history".
@ -1025,6 +1032,7 @@ var PlacesQueryBuilder = {
var ViewMenu = {
/**
* Removes content generated previously from a menupopup.
*
* @param {object} popup
* The popup that contains the previously generated content.
* @param {string} startID
@ -1078,6 +1086,7 @@ var ViewMenu = {
/**
* Fills a menupopup with a list of columns
*
* @param {object} event
* The popupshowing event that invoked this function.
* @param {string} startID
@ -1190,6 +1199,7 @@ var ViewMenu = {
/**
* Shows/Hides a tree column.
*
* @param {object} element
* The menuitem element for the column
*/
@ -1210,6 +1220,7 @@ var ViewMenu = {
/**
* Gets the last column that was sorted.
*
* @returns {object|null} the currently sorted column, null if there is no sorted column.
*/
_getSortColumn: function VM__getSortColumn() {
@ -1227,6 +1238,7 @@ var ViewMenu = {
/**
* Sorts the view by the specified column.
*
* @param {object} aColumn
* The colum that is the sort key. Can be null - the
* current sort column or the title column will be used.
@ -1328,6 +1340,7 @@ var ContentArea = {
/**
* Sets a custom view to be used rather than the default places tree
* whenever the given query is selected in the left pane.
*
* @param {string} aQueryString
* a query string
* @param {object} aView

20
browser/components/places/content/treeView.js
View File

@ -97,13 +97,14 @@ PlacesTreeView.prototype = {
* build these children lazily as the tree asks us for information about each
* row. Luckily, the tree doesn't ask about rows outside the visible area.
*
* @see _getNodeForRow and _getRowForNode for the actual magic.
*
* @note It's guaranteed that all containers are listed in the rows
* It's guaranteed that all containers are listed in the rows
* elements array. It's also guaranteed that separators (if they're not
* filtered, see below) are listed in the visible elements array, because
* bookmark folders are never built lazily, as described above.
*
* @see {@link PlacesTreeView._getNodeForRow} and
* {@link PlacesTreeView._getRowForNode} for the actual magic.
*
* @param {object} aContainer
* A container result node.
*
@ -137,6 +138,10 @@ PlacesTreeView.prototype = {
* Gets the row number for a given node. Assumes that the given node is
* visible (i.e. it's not an obsolete node).
*
* If aParentRow and aNodeIndex are passed and parent is a plain
* container, this method will just return a calculated row value, without
* making assumptions on existence of the node at that position.
*
* @param {object} aNode
* A result node. Do not pass an obsolete node, or any
* node which isn't supposed to be in the tree (e.g. separators in
@ -152,9 +157,6 @@ PlacesTreeView.prototype = {
* set too.
*
* @throws if aNode is invisible.
* @note If aParentRow and aNodeIndex are passed and parent is a plain
* container, this method will just return a calculated row value, without
* making assumptions on existence of the node at that position.
* @returns {object} aNode's row if it's in the rows list or if aForceBuild is set, -1
* otherwise.
*/
@ -233,7 +235,7 @@ PlacesTreeView.prototype = {
*
* @param {number} aChildRow
* Row number.
* @returns {array} [parentNode, parentRow]
* @returns {Array} [parentNode, parentRow]
*/
_getParentByChildRow: function PTV__getParentByChildRow(aChildRow) {
let node = this._getNodeForRow(aChildRow);
@ -306,7 +308,7 @@ PlacesTreeView.prototype = {
* @param {object} aFirstChildRow
* The first row at which nodes may be inserted to the row array.
* In other words, that's aContainer's row + 1.
* @param {array} aToOpen
* @param {Array} aToOpen
* An array of containers to open once the build is done (out param)
*
* @returns {number} the number of rows which were inserted.
@ -516,7 +518,7 @@ PlacesTreeView.prototype = {
* Restores a given selection state as near as possible to the original
* selection state.
*
* @param {array} aNodesInfo
* @param {Array} aNodesInfo
* The persisted selection state as returned by
* _getSelectedNodesInRange.
* @param {object} aUpdatedContainer

12
browser/components/places/metadataViewer/interactionsViewer.js
View File

@ -24,14 +24,15 @@ class TableViewer {
/**
* Maximum number of rows to display by default.
*
* @typedef {number}
* @type {number}
*/
maxRows = 100;
/**
* The number of rows that we last filled in on the table. This allows
* tracking to know when to clear unused rows.
* @typedef {number}
*
* @type {number}
*/
#lastFilledRows = 0;
@ -45,13 +46,14 @@ class TableViewer {
* - includeTitle determines if the title attribute should be set on that
* column, for tooltips, e.g. if an element is likely to overflow.
*
* @typedef {Map<string, object>}
* @type {Map<string, object>}
*/
columnMap;
/**
* A reference for the current interval timer, if any.
* @typedef {number}
*
* @type {number}
*/
#timer;
@ -233,7 +235,7 @@ const metadataHandler = new (class extends TableViewer {
/**
* A reference to the database connection.
*
* @typedef {mozIStorageConnection}
* @type {mozIStorageConnection}
*/
#db = null;

2
browser/components/places/tests/browser/browser_drag_bookmarks_on_toolbar.js
View File

@ -18,7 +18,7 @@ var dragDirections = { LEFT: 0, UP: 1, RIGHT: 2, DOWN: 3 };
*
* @param {object} aElement
* DOM node element we will drag
* @param {array} aExpectedDragData
* @param {Array} aExpectedDragData
* Array of flavors and values in the form:
* [ ["text/plain: sometext", "text/html: <b>sometext</b>"], [...] ]
* Pass an empty array to check that drag even has been canceled.

2
browser/components/places/tests/browser/browser_library_views_liveupdate.js
View File

@ -196,7 +196,7 @@ async function removeAndCheckItem(itemData) {
* item guid of the item to search.
* @param {object} aTree
* Tree to search in.
* @returns {array}
* @returns {Array}
* [node, index, cellText] or [null, null, ""] if not found.
*/
function getNodeForTreeItem(aItemGuid, aTree) {

2
browser/components/places/tests/browser/browser_toolbar_drop_bookmarklet.js
View File

@ -36,8 +36,6 @@ add_task(async function test() {
*
* @param {string} aEffect
* The effect to use for the drop operation: move, copy, or link.
* @param {string} aMimeType
* The mime type to use for the drop operation.
*/
let simulateDragDrop = async function(aEffect) {
info("Simulates drag/drop of a new javascript:URL to the bookmarks");

3
browser/components/places/tests/browser/browser_toolbar_overflow.js
View File

@ -371,6 +371,7 @@ add_task(async function test_separator_first() {
/**
* If the passed-in condition is fulfilled, awaits for the toolbar nodes
* visibility to have been updated.
*
* @param {boolean} [condition] Awaits for visibility only if this condition is true.
* @returns {Promise} resolved when the condition is not fulfilled or the
* visilibily update happened.
@ -388,6 +389,7 @@ function promiseUpdateVisibility(condition = true) {
/**
* Returns an array of toolbar children that are Places nodes, ignoring things
* like the chevron or other additional buttons.
*
* @returns {Array} An array of Places element nodes.
*/
function getPlacesChildren() {
@ -399,6 +401,7 @@ function getPlacesChildren() {
/**
* Toggles the toolbar on or off.
*
* @param {boolean} show Whether to show or hide the toolbar.
* @param {number} [expectedMinChildCount] Optional number of Places nodes that
* should be visible on the toolbar.

20
browser/components/places/tests/browser/browser_views_liveupdate.js
View File

@ -308,9 +308,9 @@ var bookmarksObserver = {
* item guid of the item to search.
* @param {string} view
* either "toolbar", "menu" or "sidebar"
* @param {function} validator
* @param {Function} validator
* function to check validity of the found node element.
* @returns {array}
* @returns {Array}
* [node, index, valid] or [null, null, false] if not found.
*/
function searchItemInView(itemGuid, view, validator) {
@ -331,9 +331,9 @@ function searchItemInView(itemGuid, view, validator) {
*
* @param {string} itemGuid
* item guid of the item to search.
* @param {function} validator
* @param {Function} validator
* function to check validity of the found node element.
* @returns {array}
* @returns {Array}
* [node, index] or [null, null] if not found.
*/
function getNodeForToolbarItem(itemGuid, validator) {
@ -378,9 +378,9 @@ function getNodeForToolbarItem(itemGuid, validator) {
*
* @param {string} itemGuid
* item guid of the item to search.
* @param {function} validator
* @param {Function} validator
* function to check validity of the found node element.
* @returns {array}
* @returns {Array}
* [node, index] or [null, null] if not found.
*/
function getNodeForMenuItem(itemGuid, validator) {
@ -426,9 +426,9 @@ function getNodeForMenuItem(itemGuid, validator) {
*
* @param {string} itemGuid
* item guid of the item to search.
* @param {function} validator
* @param {Function} validator
* function to check validity of the found node element.
* @returns {array}
* @returns {Array}
* [node, index] or [null, null] if not found.
*/
function getNodeForSidebarItem(itemGuid, validator) {
@ -491,9 +491,9 @@ function getNodeForSidebarItem(itemGuid, validator) {
/**
* Get views affected by changes to a folder.
*
* @param {string} folderGuid:
* @param {string} folderGuid
* item guid of the folder we have changed.
* @returns {array}
* @returns {Array<"toolbar" | "menu" | "sidebar">}
* subset of views: ["toolbar", "menu", "sidebar"]
*/
async function getViewsForFolder(folderGuid) {

18
browser/components/places/tests/browser/head.js
View File

@ -103,7 +103,7 @@ function checkLibraryPaneVisibility(library, selectedPane) {
*
* @see waitForClipboard
*
* @param {function} aPopulateClipboardFn
* @param {Function} aPopulateClipboardFn
* Function to populate the clipboard.
* @param {string} aFlavor
* Data flavor to expect.
@ -161,10 +161,8 @@ function synthesizeClickOnSelectedTreeCell(aTree, aOptions) {
* @param {boolean} aVisible
* True to make the toolbar visible, false to make it hidden.
*
* @returns {Promise}
* @resolves Any animation associated with updating the toolbar's visibility has
* finished.
* @rejects Never.
* @returns {Promise} Any animation associated with updating the toolbar's
* visibility has finished.
*/
function promiseSetToolbarVisibility(aToolbar, aVisible) {
if (isToolbarVisible(aToolbar) != aVisible) {
@ -199,11 +197,11 @@ function isToolbarVisible(aToolbar) {
*
* @param {boolean} autoCancel
* whether to automatically cancel the dialog at the end of the task
* @param {function} openFn
* @param {Function} openFn
* generator function causing the dialog to open
* @param {function} taskFn
* @param {Function} taskFn
* the task to execute once the dialog is open
* @param {function} closeFn
* @param {Function} closeFn
* A function to be used to wait for pending work when the dialog is
* closing. It is passed the dialog window handle and should return a promise.
* @param {string} [dialogUrl]
@ -387,7 +385,7 @@ function fillBookmarkTextField(id, text, win, blur = true) {
*
* @param {string} type
* either "bookmarks" or "history".
* @param {function} taskFn
* @param {Function} taskFn
* The task to execute once the sidebar is ready. Will get the Places
* tree view as input.
*/
@ -426,7 +424,7 @@ var withSidebarTree = async function(type, taskFn) {
*
* @param {string} hierarchy
* The left pane hierarchy to open.
* @param {function} taskFn
* @param {Function} taskFn
* The task to execute once the Library is ready.
* Will get { left, right } trees as argument.
*/

2
browser/components/places/tests/browser/interactions/head.js
View File

@ -36,6 +36,7 @@ add_setup(async function global_setup() {
/**
* Ensures that a list of interactions have been permanently stored.
*
* @param {Array} expected list of interactions to be found.
* @param {boolean} [dontFlush] Avoid flushing pending data.
*/
@ -166,6 +167,7 @@ async function assertDatabaseValues(expected, { dontFlush = false } = {}) {
/**
* Ensures that a list of interactions have been permanently stored.
*
* @param {string} url The url to query.
* @param {string} property The property to extract.
*/

7
browser/components/places/tests/unit/head_bookmarks.js
View File

@ -61,7 +61,7 @@ const NUMBER_OF_TRIES = 30;
* Similar to waitForConditionPromise, but poll for an asynchronous value
* every SINGLE_TRY_TIMEOUT ms, for no more than tryCount times.
*
* @param {function} promiseFn
* @param {Function} promiseFn
* A function to generate a promise, which resolves to the expected
* asynchronous value.
* @param {msg} timeoutMsg
@ -69,9 +69,8 @@ const NUMBER_OF_TRIES = 30;
* @param {number} [tryCount]
* Maximum times to try before rejecting the returned promise with
* timeoutMsg, defaults to NUMBER_OF_TRIES.
* @returns {Promise}
* @resolves to the asynchronous value being polled.
* @rejects if the asynchronous value is not available after tryCount attempts.
* @returns {Promise} to the asynchronous value being polled.
* @throws if the asynchronous value is not available after tryCount attempts.
*/
var waitForResolvedPromise = async function(
promiseFn,

5
browser/components/places/tests/unit/interactions/head_interactions.js
View File

@ -95,7 +95,7 @@ async function getInteractions() {
*
* @param {string} topic
* @param {string[]} expected
* @param {function} task
* @param {Function} task
*/
async function assertUrlNotification(topic, expected, task) {
let seen = false;
@ -130,7 +130,7 @@ async function assertUrlNotification(topic, expected, task) {
* not sent.
*
* @param {string} topic
* @param {function} task
* @param {Function} task
*/
async function assertTopicNotObserved(topic, task) {
let seen = false;
@ -456,6 +456,7 @@ function assertRecommendations(recommendations, expected) {
/**
* Abstracts getting the right moz-page-thumb url depending on enabled features.
*
* @param {string} url
* The page url to get a screenshot for.
* @returns {string} a moz-page-thumb:// url

1
browser/components/places/tests/unit/interactions/test_snapshots_protocols.js
View File

@ -16,6 +16,7 @@ const TEST_LOCAL_JSON_FILE = "file:///Users/user/test.json";
/**
* Creates an interaction and snapshot for the given url
* Returns the result of a query for the snapshot
*
* @param {string} url
* The url to create the interaction and snapshot for
*/