commit 5c05ba42f8dc1e85151dac3fba7a32a64fa22b98 parent 9fd3239965a5283dff3c0b6fa8d76b519f5b107e Author: Mark Banner <standard8@mozilla.com> Date: Tue, 30 Sep 2025 15:10:54 +0000 Bug 1991124 - Fix ESLint require-jsdoc issues in places code. r=daisuke,places-reviewers Differential Revision: https://phabricator.services.mozilla.com/D266633 Diffstat:
21 files changed, 131 insertions(+), 36 deletions(-)
diff --git a/eslint-rollouts.config.mjs b/eslint-rollouts.config.mjs @@ -522,26 +522,6 @@ export default [ "browser/extensions/ipp-activator/extension/conditions/test.mjs", "browser/extensions/ipp-activator/extension/conditions/url.mjs", "toolkit/components/promiseworker/PromiseWorker.sys.mjs", - "toolkit/components/places/PlacesDBUtils.sys.mjs", - "toolkit/components/places/PlacesSemanticHistoryDatabase.sys.mjs", - "toolkit/components/places/PlacesSemanticHistoryManager.sys.mjs", - "toolkit/components/places/PlacesSyncUtils.sys.mjs", - "toolkit/components/places/PlacesTransactions.sys.mjs", - "toolkit/components/places/tests/bookmarks/test_sync_fields.js", - "toolkit/components/places/tests/browser/browser_settitle.js", - "toolkit/components/places/tests/browser/browser_visituri_nohistory.js", - "toolkit/components/places/tests/chrome/test_cached_favicon.xhtml", - "toolkit/components/places/tests/head_common.js", - "toolkit/components/places/tests/queries/head_queries.js", - "toolkit/components/places/tests/queries/test_async.js", - "toolkit/components/places/tests/queries/test_querySerialization.js", - "toolkit/components/places/tests/queries/test_tags.js", - "toolkit/components/places/tests/unit/test_PlacesSemanticHistoryManager.js", - "toolkit/components/places/tests/unit/test_bookmarks_restore_notification.js", - "toolkit/components/places/tests/unit/test_history_observer.js", - "toolkit/components/places/tests/unit/test_history_sidebar.js", - "toolkit/components/places/tests/unit/test_keywords.js", - "toolkit/components/places/tests/unit/test_nested_notifications.js", "toolkit/components/search/SearchSuggestionController.sys.mjs", "toolkit/modules/AppServicesTracing.sys.mjs", ], diff --git a/toolkit/components/places/PlacesDBUtils.sys.mjs b/toolkit/components/places/PlacesDBUtils.sys.mjs @@ -933,6 +933,8 @@ export var PlacesDBUtils = { * * @typedef {object} ExpirationWrappedJSObject * @property {function(): Promise<number>} getPagesLimit + * A function that returns the maximum number of pages that should be + * retained. */ // This has to be type cast because wrappedJSObject is an object. diff --git a/toolkit/components/places/PlacesSemanticHistoryDatabase.sys.mjs b/toolkit/components/places/PlacesSemanticHistoryDatabase.sys.mjs @@ -37,6 +37,9 @@ const MAX_WASTED_SPACE_PERC = 0.6; // Maximum number of _chunksNN tables in sqlite-vec. const MAX_CHUNKS_TABLES = 100; +/** + * Handles the database connection, reading and writing for semantic history. + */ export class PlacesSemanticHistoryDatabase { #asyncShutdownBlocker; #conn; diff --git a/toolkit/components/places/PlacesSemanticHistoryManager.sys.mjs b/toolkit/components/places/PlacesSemanticHistoryManager.sys.mjs @@ -3,9 +3,6 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ /** - * PlacesSemanticHistoryManager manages the semantic.sqlite database and provides helper - * methods for initializing, querying, and updating semantic data. - * * This module handles embeddings-based semantic search capabilities using the * Places database and an ML engine for vector operations. */ @@ -49,6 +46,10 @@ const ONE_MiB = 1024 * 1024; // minimum title length threshold; Usage len(title || description) > MIN_TITLE_LENGTH const MIN_TITLE_LENGTH = 4; +/** + * PlacesSemanticHistoryManager manages the semantic.sqlite database and provides helper + * methods for initializing, querying, and updating semantic data. + */ class PlacesSemanticHistoryManager { #promiseConn; #engine = undefined; diff --git a/toolkit/components/places/PlacesSyncUtils.sys.mjs b/toolkit/components/places/PlacesSyncUtils.sys.mjs @@ -726,6 +726,9 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ /** * Converts a Places GUID to a Sync record ID. Record IDs are identical to * Places GUIDs for all items except roots. + * + * @param {string} guid + * @returns {string} */ guidToRecordId(guid) { return lazy.ROOT_GUID_TO_RECORD_ID[guid] || guid; @@ -733,6 +736,9 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ /** * Converts a Sync record ID to a Places GUID. + * + * @param {string} recordId + * @returns {string} */ recordIdToGuid(recordId) { return lazy.ROOT_RECORD_ID_TO_GUID[recordId] || recordId; @@ -742,6 +748,9 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ * Fetches the record IDs for a folder's children, ordered by their position * within the folder. * Used only be tests - but that includes tps, so it lives here. + * + * @param {string} parentRecordId + * @returns {Promise<string[]>} */ fetchChildRecordIds(parentRecordId) { lazy.PlacesUtils.SYNC_BOOKMARK_VALIDATORS.recordId(parentRecordId); @@ -757,12 +766,15 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ }, /** - * Migrates an array of `{ recordId, modified }` tuples from the old JSON-based - * tracker to the new sync change counter. `modified` is when the change was - * added to the old tracker, in milliseconds. + * Migrates an array of tuples from the old JSON-based tracker to the new sync + * change counter. * * Sync calls this method before the first bookmark sync after the Places * schema migration. + * + * @param {{recordId: string, modified: number}[]} entries + * `recordId` is the record identifier. `modified` is when the change was + * added to the old tracker, in milliseconds. */ migrateOldTrackerEntries(entries) { return lazy.PlacesUtils.withConnectionWrapper( @@ -1067,6 +1079,8 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ * * See the comment above `BookmarksStore::deletePending` for the details on * why delete works the way it does. + * + * @param {string[]} recordIds */ remove(recordIds) { if (!recordIds.length) { @@ -1184,6 +1198,8 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ * children, used to determine child order. * - folder ("query"): The tag folder name, if this is a tag query. * - index ("separator"): The separator's position within its parent. + * + * @param {string} recordId */ async fetch(recordId) { let guid = BookmarkSyncUtils.recordIdToGuid(recordId); @@ -1237,6 +1253,8 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ /** * Returns the sync change counter increment for a change source constant. + * + * @param {string} source */ determineSyncChangeDelta(source) { // Don't bump the change counter when applying changes made by Sync, to @@ -1246,6 +1264,8 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ /** * Returns the sync status for a new item inserted by a change source. + * + * @param {string} source */ determineInitialSyncStatus(source) { if (source == lazy.PlacesUtils.bookmarks.SOURCES.SYNC) { @@ -1300,6 +1320,10 @@ const BookmarkSyncUtils = (PlacesSyncUtils.bookmarks = Object.freeze({ * Returns `0` if no sensible timestamp could be found. * Otherwise, returns the earliest sensible timestamp between `existingMillis` * and `serverMillis`. + * + * @param {number} existingMillis + * @param {number} serverMillis + * @param {number} [lowerBound] */ ratchetTimestampBackwards( existingMillis, @@ -1987,6 +2011,9 @@ var deleteSyncedAtom = async function (bookmarkItem) { * we write tombstones if a new item is deleted after an interrupted sync. (For * example, if a "NEW" record is uploaded or reconciled, then the app is closed * before Sync calls `pushChanges`). + * + * @param {OpenedConnection} db + * @param {object} changeRecords */ function markChangesAsSyncing(db, changeRecords) { let unsyncedGuids = []; @@ -2018,6 +2045,8 @@ function markChangesAsSyncing(db, changeRecords) { /** * Removes tombstones for successfully synced items. * + * @param {OpenedConnection} db + * @param {string[]} guids * @returns {Promise} */ var removeTombstones = function (db, guids) { @@ -2033,6 +2062,8 @@ var removeTombstones = function (db, guids) { * Removes tombstones for successfully synced items where the specified GUID * exists in *both* the bookmarks and tombstones tables. * + * @param {OpenedConnection} db + * @param {string[]} guids * @returns {Promise} */ var removeUndeletedTombstones = function (db, guids) { diff --git a/toolkit/components/places/PlacesTransactions.sys.mjs b/toolkit/components/places/PlacesTransactions.sys.mjs @@ -164,6 +164,10 @@ ChromeUtils.defineLazyGetter(lazy, "logger", function () { return PlacesUtils.getLogger({ prefix: "Transactions" }); }); +/** + * Keeps track of the history of transactions, including their redo and undo + * points. + */ class TransactionsHistoryArray extends Array { constructor() { super(); @@ -303,6 +307,9 @@ ChromeUtils.defineLazyGetter( export var PlacesTransactions = { /** * @see Batches in the module documentation. + * + * @param {object[]} transactionsToBatch + * @param {string} batchName */ batch(transactionsToBatch, batchName) { if (!Array.isArray(transactionsToBatch) || !transactionsToBatch.length) { @@ -460,6 +467,8 @@ export var PlacesTransactions = { * * In other words: Enqueuer.enqueue(aFunc1); Enqueuer.enqueue(aFunc2) is roughly * the same as asyncFunc1.then(asyncFunc2). + * + * @param {string} name */ function Enqueuer(name) { this._promise = Promise.resolve(); @@ -672,6 +681,9 @@ var TransactionsManager = { * consumers. * (2) It keeps each transaction implementation to what is about, bypassing * all this bureaucracy while still validating input appropriately. + * + * @param {string[]} [requiredProps] + * @param {string[]} [optionalProps] */ function DefineTransaction(requiredProps = [], optionalProps = []) { for (let prop of [...requiredProps, ...optionalProps]) { @@ -680,7 +692,10 @@ function DefineTransaction(requiredProps = [], optionalProps = []) { } } - /** @this {{ execute: Function }} */ + /** + * @this {{ execute: Function }} + * @param {object} input + */ let ctor = function (input) { // We want to support both syntaxes: // let t = new PlacesTransactions.NewBookmark(), diff --git a/toolkit/components/places/tests/bookmarks/test_sync_fields.js b/toolkit/components/places/tests/bookmarks/test_sync_fields.js @@ -1,6 +1,8 @@ -// Tracks a set of bookmark guids and their syncChangeCounter field and -// provides a simple way for the test to check the correct fields had the -// counter incremented. +/** + * Tracks a set of bookmark guids and their syncChangeCounter field and + * provides a simple way for the test to check the correct fields had the + * counter incremented. + */ class CounterTracker { constructor() { this.tracked = new Map(); @@ -67,7 +69,9 @@ async function checkSyncFields(guid, expected) { } } -// Common test cases for sync field changes. +/** + * Common test cases for sync field changes. + */ class TestCases { async run() { info("Test 1: inserts, updates, tags, and keywords"); @@ -283,8 +287,10 @@ class TestCases { } } -// Exercises the legacy, synchronous `nsINavBookmarksService` calls implemented -// in C++. +/** + * Exercises the legacy, synchronous `nsINavBookmarksService` calls implemented + * in C++. + */ class SyncTestCases extends TestCases { async createFolder(parentGuid, title, index) { let parentId = await PlacesTestUtils.promiseItemId(parentGuid); @@ -331,7 +337,9 @@ async function findTagFolder(tag) { return results.length ? results[0].getResultByName("guid") : null; } -// Exercises the new, async calls implemented in `Bookmarks.sys.mjs`. +/** + * Exercises the new, async calls implemented in `Bookmarks.sys.mjs`. + */ class AsyncTestCases extends TestCases { async createFolder(parentGuid, title, index) { let item = await PlacesUtils.bookmarks.insert({ diff --git a/toolkit/components/places/tests/browser/browser_settitle.js b/toolkit/components/places/tests/browser/browser_settitle.js @@ -2,6 +2,10 @@ var conn = PlacesUtils.history.DBConnection; /** * Gets a single column value from either the places or historyvisits table. + * + * @param {string} table + * @param {string} column + * @param {string} url */ function getColumn(table, column, url) { var stmt = conn.createStatement( diff --git a/toolkit/components/places/tests/browser/browser_visituri_nohistory.js b/toolkit/components/places/tests/browser/browser_visituri_nohistory.js @@ -10,6 +10,8 @@ const FINAL_URL = /** * One-time observer callback. + * + * @param {string} name */ function promiseObserve(name) { return new Promise(resolve => { diff --git a/toolkit/components/places/tests/chrome/test_cached_favicon.xhtml b/toolkit/components/places/tests/chrome/test_cached_favicon.xhtml @@ -46,6 +46,10 @@ function loadEventHandler() /** * This runs the comparison. + * + * @param {number} aIndex + * @param {string} aImage1 + * @param {string} aImage2 */ function compareResults(aIndex, aImage1, aImage2) { diff --git a/toolkit/components/places/tests/head_common.js b/toolkit/components/places/tests/head_common.js @@ -132,6 +132,7 @@ function DBConn(aForceNewConnection) { /** * Reads data from the provided inputstream. * + * @param {nsIInputStream} aStream * @returns {number[]} * An array of bytes. */ @@ -724,6 +725,8 @@ function checkBookmarkObject(info) { /** * Reads foreign_count value for a given url. + * + * @param {string|nsIURI} url */ async function foreign_count(url) { if (url instanceof Ci.nsIURI) { @@ -755,6 +758,10 @@ function sortBy(array, prop) { /** * Asynchronously compares contents from 2 favicon urls. + * + * @param {string|nsIURI} icon1 + * @param {string|nsIURI} icon2 + * @param {string} msg */ async function compareFavicons(icon1, icon2, msg) { icon1 = new URL(icon1 instanceof Ci.nsIURI ? icon1.spec : icon1); diff --git a/toolkit/components/places/tests/queries/head_queries.js b/toolkit/components/places/tests/queries/head_queries.js @@ -29,6 +29,8 @@ const olderthansixmonths = today - DAY_MICROSEC * 31 * 7; * the database. It does NOT do any checking to see that the input is * appropriate. This function is an asynchronous task, it can be called using * "Task.spawn" or using the "yield" function inside another task. + * + * @param {object} aArray */ async function task_populateDB(aArray) { // Iterate over aArray and execute all instructions. @@ -153,6 +155,8 @@ async function task_populateDB(aArray) { * For ex: * var myobj = new queryData({isVisit: true, uri:"http://mozilla.com", title="foo"}); * Note that it doesn't do any input checking on that object. + * + * @param {object} obj */ function queryData(obj) { this.isVisit = obj.isVisit ? obj.isVisit : false; @@ -199,6 +203,9 @@ queryData.prototype = {}; * It assumes the array of query objects contains the SAME SORT as the result * set. It checks the the uri, title, time, and bookmarkIndex properties of * the results, where appropriate. + * + * @param {object[]} aArray + * @param {nsINavHistoryContainerResultNode} aRoot */ function compareArrayToResult(aArray, aRoot) { info("Comparing Array to Results"); @@ -278,6 +285,8 @@ function compareArrayToResult(aArray, aRoot) { * objects. If it gets an array, it only compares the first object in the array * to see if it is in the result set. * + * @param {object} aQueryData + * @param {nsINavHistoryContainerResultNode} aRoot * @returns {nsINavHistoryResultNode}: Either the node, if found, or null. * If input is an array, returns a result only for the first node. * To compare entire array, use the function above. @@ -314,6 +323,8 @@ function nodeInResult(aQueryData, aRoot) { /** * A nice helper function for debugging things. It prints the contents of a * result set. + * + * @param {nsINavHistoryContainerResultNode} aRoot */ function displayResultSet(aRoot) { var wasOpen = aRoot.containerOpen; diff --git a/toolkit/components/places/tests/queries/test_async.js b/toolkit/components/places/tests/queries/test_async.js @@ -140,6 +140,9 @@ Test.prototype = { * the state change and ensures that it has been observed the given number * of times. See checkState for parameter explanations. * + * @param {string} aState + * @param {number} aExpectedMin + * @param {number} aExpectedMax * @returns {number} * The number of times aState has been observed, including the new observation. */ diff --git a/toolkit/components/places/tests/queries/test_querySerialization.js b/toolkit/components/places/tests/queries/test_querySerialization.js @@ -514,6 +514,7 @@ function cartProd(aSequences, aCallback) { * An array from which to choose elements, aSet.length > 0. * @param {number} aHowMany * The number of elements to choose, > 0 and <= aSet.length. + * @param {number[]} aCallback * @returns {number} * The total number of sets chosen. */ diff --git a/toolkit/components/places/tests/queries/test_tags.js b/toolkit/components/places/tests/queries/test_tags.js @@ -610,6 +610,10 @@ function queryURI(aQuery, aQueryOpts) { /** * Ensures that the arrays contain the same elements and, optionally, in the * same order. + * + * @param {*[]} aArr1 + * @param {*[]} aArr2 + * @param {boolean} aIsOrdered */ function setsAreEqual(aArr1, aArr2, aIsOrdered) { Assert.equal(aArr1.length, aArr2.length); diff --git a/toolkit/components/places/tests/unit/test_PlacesSemanticHistoryManager.js b/toolkit/components/places/tests/unit/test_PlacesSemanticHistoryManager.js @@ -30,11 +30,12 @@ function createPlacesSemanticHistoryManager(options = {}) { ); } +/** + * Mock engine that simulates an ML embedding engine. + */ class MockMLEngine { #entries; /** - * Mock engine that simulates an ML embedding engine. - * * @param {Array} entries - Array of entries with title and vector properties. */ constructor(entries = []) { diff --git a/toolkit/components/places/tests/unit/test_bookmarks_restore_notification.js b/toolkit/components/places/tests/unit/test_bookmarks_restore_notification.js @@ -114,6 +114,8 @@ async function checkObservers(expectPromises, expectedData) { /** * Run after every test cases. + * + * @param {string} file */ async function teardown(file) { // On restore failed, file may not exist, so wrap in try-catch. diff --git a/toolkit/components/places/tests/unit/test_history_observer.js b/toolkit/components/places/tests/unit/test_history_observer.js @@ -4,6 +4,8 @@ /** * Registers a one-time places observer for 'page-visited', * which resolves a promise on being called. + * + * @param {(PlacesEvent) => Promise<void>} callback */ function promiseVisitAdded(callback) { return new Promise(resolve => { @@ -20,6 +22,10 @@ function promiseVisitAdded(callback) { /** * Asynchronous task that adds a visit to the history database. + * + * @param {nsIURI} [uri] + * @param {number} [timestamp] + * @param {nsINavHistoryService.TransitionType} [transition] */ async function task_add_visit(uri, timestamp, transition) { uri = uri || NetUtil.newURI("http://firefox.com/"); diff --git a/toolkit/components/places/tests/unit/test_history_sidebar.js b/toolkit/components/places/tests/unit/test_history_sidebar.js @@ -136,6 +136,8 @@ add_task(async function task_fill_history() { /** * Bug 485703 - Hide date containers not containing additional entries compared * to previous ones. + * + * @param {number} aOffset */ function check_visit(aOffset) { let root = openRootForResultType( @@ -344,6 +346,8 @@ add_task(async function test_RESULTS_AS_SITE_QUERY() { /** * Checks that queries grouped by date do liveupdate correctly. + * + * @param {nsINavHistoryQueryOptions.ResultType} aResultType */ async function test_date_liveupdate(aResultType) { let midnight = toMidnight(nowObj); diff --git a/toolkit/components/places/tests/unit/test_keywords.js b/toolkit/components/places/tests/unit/test_keywords.js @@ -51,6 +51,9 @@ async function check_keyword(aExpectExists, aHref, aKeyword, aPostData = null) { /** * Polls the keywords cache waiting for the given keyword entry. + * + * @param {string} keyword + * @param {string} expectedHref */ async function promiseKeyword(keyword, expectedHref) { let href = null; diff --git a/toolkit/components/places/tests/unit/test_nested_notifications.js b/toolkit/components/places/tests/unit/test_nested_notifications.js @@ -128,6 +128,9 @@ function notifyPlacesEvent(guid) { ]); } +/** + * An observer which stores an array of the notifications received. + */ class Observer { constructor() { this.notifications = [];