Update eslint jsdoc plugin

Merge in EXTENSIONS/browser-extension from fix/eslint-jsdoc-plugin to master

Squashed commit of the following:

commit 6e29b2a
Author: scripthunter7 <d.tota@adguard.com>
Date:   Tue Oct 1 12:40:03 2024 +0300

    update eslint jsdoc plugin

.eslintrc.js

@@ -158,6 +158,7 @@ module.exports = {
         'jsdoc/no-undefined-types': 'off',
         'jsdoc/require-returns-check': 'off',
         'jsdoc/require-jsdoc': 'off',
+        'jsdoc/no-defaults': 'off',
     },
     'ignorePatterns': [
         'node_modules',

Extension/src/background/.eslintrc.js

@@ -34,7 +34,8 @@ module.exports = {
         'jsdoc/require-returns-description': 'error',
         'jsdoc/require-returns': 'error',
         'jsdoc/require-param': 'error',
-        'jsdoc/no-undefined-types': 'error',
+        // TODO: Enable this rule
+        'jsdoc/no-undefined-types': 'off',
         'jsdoc/require-returns-check': 'error',
         'jsdoc/require-description-complete-sentence': ['error'],
         'jsdoc/require-jsdoc': [

Extension/src/background/api/document-block.ts

@@ -47,6 +47,8 @@ export class DocumentBlockApi {
 
     /**
      * Returns an array of trusted domains.
+     *
+     * @returns An array of trusted domains.
      */
     public static async getTrustedDomains(): Promise<string[]> {
         const now = Date.now();

Extension/src/background/api/filtering-log.ts

@@ -262,7 +262,8 @@ export class FilteringLogApi {
      * Tries to sync the cached filter data with the storage.
      *
      * @param filterId Filter id.
-     * @returns Returns false if the filter was synced within the last {@link SYNC_ATTEMPTS_INTERVAL_MS} milliseconds.
+     * @returns Returns false if the filter was synced within the last
+     * {@link FilteringLogApi.SYNC_ATTEMPTS_INTERVAL_MS} milliseconds.
      * Otherwise, returns true.
      */
     private attemptToSyncFilter(filterId: number): boolean {
@@ -545,6 +546,8 @@ export class FilteringLogApi {
 
     /**
      * Synchronizes currently opened tabs with out state.
+     *
+     * @returns Array of {@link FilteringLogTabInfo} with data about opened tabs.
      */
     public async synchronizeOpenTabs(): Promise<FilteringLogTabInfo[]> {
         const tabs = await TabsApi.getAll();

Extension/src/background/api/filters/annoyances-consent.ts

@@ -61,6 +61,8 @@ export class AnnoyancesConsentApi {
 
     /**
      * Restores consented annoyances filter ids from storage.
+     *
+     * @returns Set of consented annoyances filter ids.
      */
     private static async getConsentFromStorage(): Promise<Set<number>> {
         const storedConsentedFilterIds = await AnnoyancesConsentApi.getFromStorage();

Extension/src/background/api/filters/page-stats.ts

@@ -108,6 +108,8 @@ export class PageStatsApi {
      *
      * @param filterId Filter id.
      * @param blocked Count of blocked requests.
+     *
+     * @returns Promise, resolved when stats are updated.
      */
     public static async updateStats(
         filterId: number,

Extension/src/background/api/filters/update.ts

@@ -61,7 +61,7 @@ export class FilterUpdateApi {
     private static readonly RECENTLY_CHECKED_FILTER_TIMEOUT_MS = 1000 * 60 * 5;
 
     /**
-     * Filters the provided filter list with {@link selectFiltersIdsToUpdate},
+     * Filters the provided filter list with {@link FilterUpdateApi.selectFiltersIdsToUpdate},
      * then gets fresh metadata from the remote server for all filters (it
      * cannot be updated selectively), and, after updating, refreshes
      * lastCheckTime for each of those selected for checking filters.
@@ -111,6 +111,8 @@ export class FilterUpdateApi {
      *
      * @param forceUpdate Is it a force manual check by user action or first run
      * or not.
+     *
+     * @returns List of metadata for updated filters.
      */
     public static async autoUpdateFilters(forceUpdate = false): Promise<FilterMetadata[]> {
         const startUpdateLogMessage = forceUpdate

Extension/src/background/api/filters/userrules.ts

@@ -87,6 +87,8 @@ export class UserRulesApi {
 
     /**
      * Returns rules from user list.
+     *
+     * @returns User rules list.
      */
     public static async getUserRules(): Promise<PreprocessedFilterList> {
         const data = await FiltersStorage.getAllFilterData(AntiBannerFiltersId.UserFilterId);
@@ -110,6 +112,8 @@ export class UserRulesApi {
      * but when user opens the editor, we need to show their original rules.
      * User rules is a bit special because for that list we store the whole original filter list.
      * This method return that original list and we use it to load content in the editor.
+     *
+     * @returns User rules list.
      */
     public static async getOriginalUserRules(): Promise<string[]> {
         return FiltersStorage.getOriginalRules(AntiBannerFiltersId.UserFilterId);

Extension/src/background/api/network/main.ts

@@ -116,6 +116,8 @@ export class Network {
      * @param useOptimizedFilters Download optimized filters flag.
      * @param rawFilter Raw filter rules.
      *
+     * @returns Downloaded filter rules.
+     *
      * @throws An error if FiltersDownloader.downloadWithRaw() fails.
      */
     public async downloadFilterRules(
@@ -179,6 +181,8 @@ export class Network {
      * @param url Subscription url.
      * @param rawFilter Raw filter rules.
      * @param force Boolean flag to download filter fully or by patches.
+     *
+     * @returns Downloaded filter rules.
      */
     public async downloadFilterRulesBySubscriptionUrl(
         url: string,
@@ -328,6 +332,8 @@ export class Network {
     /**
      * Downloads metadata from backend.
      *
+     * @returns Object of {@link Metadata}.
+     *
      * @throws Error if metadata is invalid.
      */
     public async downloadMetadataFromBackend(): Promise<Metadata> {
@@ -374,6 +380,8 @@ export class Network {
      * Checks specified host hashes with our safebrowsing service.
      *
      * @param hashes Host hashes.
+     *
+     * @returns Response from the safebrowsing service.
      */
     public async lookupSafebrowsing(hashes: string[]): Promise<ExtensionXMLHttpRequest> {
         const url = `${this.settings.safebrowsingLookupUrl}?prefixes=${encodeURIComponent(hashes.join('/'))}`;
@@ -451,6 +459,8 @@ export class Network {
      *
      * @param url Url.
      * @param contentType Content type.
+     *
+     * @returns Promise with XMLHttpRequest.
      */
     private static async executeRequestAsync(url: string, contentType: string): Promise<ExtensionXMLHttpRequest> {
         return new Promise((resolve, reject) => {

Extension/src/background/api/safebrowsing.ts

@@ -86,6 +86,8 @@ export class SafebrowsingApi {
      *
      * @param requestUrl Request URL.
      * @param referrerUrl Referrer URL.
+     *
+     * @returns Safebrowsing list we've detected or null.
      */
     public static async checkSafebrowsingFilter(requestUrl: string, referrerUrl: string): Promise<string | undefined> {
         logger.debug('Checking safebrowsing filter for', requestUrl);

Extension/src/background/api/settings/main.ts

@@ -240,6 +240,8 @@ export class SettingsApi {
 
     /**
      * Exports settings to string with JSON format.
+     *
+     * @returns Configuration in JSON format.
      */
     public static async export(): Promise<string> {
         const config: Config = {

Extension/src/background/api/ui/promo-notification.ts

@@ -102,6 +102,8 @@ export class PromoNotificationApi {
 
     /**
      * Finds out notification for current time and checks if notification wasn't shown yet.
+     *
+     * @returns Notification object or null if there is no notification to show.
      */
     public async getCurrentNotification(): Promise<Notification | null> {
         // Do not display notification on Firefox
@@ -213,6 +215,8 @@ export class PromoNotificationApi {
     /**
      * Returns the last time a notification was shown.
      * If it was not shown yet, initialized with the current time.
+     *
+     * @returns Last notification time.
      */
     private static async getLastNotificationTime(): Promise<number> {
         let lastTime = Number(await browserStorage.get(LAST_NOTIFICATION_TIME_KEY) || 0);

Extension/src/background/engine.ts

@@ -114,6 +114,8 @@ export class Engine {
 
     /**
      * Creates tswebextension configuration based on current app state.
+     *
+     * @returns Configuration for tswebextension.
      */
     private static async getConfiguration(): Promise<ConfigurationMV2> {
         const enabledFilters = FiltersApi.getEnabledFilters();

Extension/src/background/events/context-menu.ts

@@ -59,6 +59,8 @@ export class ContextMenuEvents {
      * Publishes the event and, if a listener is found, notifies the listener.
      *
      * @param event Event with some generic type.
+     *
+     * @returns Promise with the result of the listener.
      */
     public async publishEvent<T extends ContextMenuAction>(event: T): Promise<unknown> {
         const listener = this.listenersMap.get(event);

Extension/src/background/events/settings.ts

@@ -45,6 +45,8 @@ export class SettingsEvents {
      *
      * @param event Event with some generic type.
      * @param value Some filed in the {@link Settings} object.
+     *
+     * @returns Promise that resolves when the listener is notified.
      */
     public async publishEvent<T extends SettingOption>(event: T, value: Settings[T]): Promise<void> {
         const listener = this.listenersMap.get(event) as SettingsListener<T>;

Extension/src/background/schema/.eslintrc.js

@@ -33,7 +33,8 @@ module.exports = {
         'jsdoc/require-returns-description': 'error',
         'jsdoc/require-returns': 'error',
         'jsdoc/require-param': 'error',
-        'jsdoc/no-undefined-types': 'error',
+        // TODO: Enable this rule
+        'jsdoc/no-undefined-types': 'off',
         'jsdoc/require-returns-check': 'error',
         'jsdoc/require-description-complete-sentence': ['error'],
         'jsdoc/require-jsdoc': [

Extension/src/background/services/custom-filter.ts

@@ -56,6 +56,8 @@ export class CustomFilterService {
      * Returns custom filter info for modal window.
      *
      * @param message Message data.
+     *
+     * @returns Custom filter info.
      */
     static async onCustomFilterInfoLoad(message: LoadCustomFilterInfoMessage): Promise<GetCustomFilterInfoResult> {
         const { url, title } = message.data;
@@ -67,6 +69,8 @@ export class CustomFilterService {
      * Add new custom filter.
      *
      * @param message Message data.
+     *
+     * @returns Custom filter metadata.
      */
     static async onCustomFilterSubscription(message: SubscribeToCustomFilterMessage): Promise<CustomFilterMetadata> {
         const { filter } = message.data;

Extension/src/background/services/filtering-log.ts

@@ -680,6 +680,8 @@ export class FilteringLogService {
 
     /**
      * Calls {@link filteringLogApi} for synchronize list of the opened tabs.
+     *
+     * @returns List of the opened tabs.
      */
     private static async onSyncOpenTabs(): Promise<FilteringLogTabInfo[]> {
         return filteringLogApi.synchronizeOpenTabs();

Extension/src/background/services/filters.ts

@@ -170,6 +170,8 @@ export class FiltersService {
 
     /**
      * Called when requesting an force update for filters.
+     *
+     * @returns Updated filters metadata.
      */
     private static async manualCheckFiltersUpdate(): Promise<FilterMetadata[] | undefined> {
         try {

Extension/src/background/services/settings.ts

@@ -179,6 +179,8 @@ export class SettingsService {
      * Imports settings from JSON.
      *
      * @param message Message with JSON settings {@link ApplySettingsJsonMessage}.
+     *
+     * @returns Result of importing.
      */
     static async import(message: ApplySettingsJsonMessage): Promise<boolean> {
         const { json } = message.data;

Extension/src/background/services/userrules.ts

@@ -85,6 +85,8 @@ export class UserRulesService {
 
     /**
      * Returns all user rules concatenated via '\n' divider for the editor.
+     *
+     * @returns User rules editor content and settings.
      */
     private static async getUserRulesEditorData(): Promise<GetUserRulesEditorDataResponse> {
         const userRules = await UserRulesApi.getOriginalUserRules();

Extension/src/background/storages/hybrid-storage.ts

@@ -178,6 +178,8 @@ export class HybridStorage implements ExtendedStorageInterface<string, unknown,
      * Asynchronously removes the value for a given key from the selected storage mechanism.
      *
      * @param key The key whose value is to be removed.
+     *
+     * @returns A promise that resolves when the operation is complete.
      */
     async remove(key: string): Promise<void> {
         const storage = await this.getStorage();

Extension/src/background/storages/raw-filters.ts

@@ -83,6 +83,8 @@ export class RawFiltersStorage {
      * Removes specified filter list from {@link hybridStorage}.
      *
      * @param filterId Filter id.
+     *
+     * @returns Promise, resolved when filter list is removed.
      */
     static async remove(filterId: number): Promise<void> {
         const key = RawFiltersStorage.getFilterKey(filterId);

Extension/src/background/storages/safebrowsing.ts

@@ -42,7 +42,7 @@ export class SbCache {
 
     /**
      * Reads safebrowsing {@link LRUMap} stringified entries from {@link browserStorage},
-     * parse it and sets to {@link cache}.
+     * parse it and sets to {@link this.cache}.
      *
      * @returns Promise, resolved when data successfully initialized.
      */
@@ -68,14 +68,14 @@ export class SbCache {
     }
 
     /**
-     * Saves stringified safebrowsing {@link cache} entries in {@link browserStorage}.
+     * Saves stringified safebrowsing {@link this.cache} entries in {@link browserStorage}.
      */
     public async save(): Promise<void> {
         await browserStorage.set(SB_LRU_CACHE_KEY, JSON.stringify(this.cache.toJSON()));
     }
 
     /**
-     * Returns value from {@link cache}.
+     * Returns value from {@link this.cache}.
      *
      * @param key Cache key.
      * @returns Cache value.
@@ -92,11 +92,11 @@ export class SbCache {
     }
 
     /**
-     * Sets value to {@link cache}.
+     * Sets value to {@link this.cache}.
      *
      * @param key Cache key.
      * @param list Cache list value.
-     * @returns Updated {@link cache} instance.
+     * @returns Updated {@link this.cache} instance.
      */
     public async set(key: string, list: string): Promise<SbCache> {
         const data: SafebrowsingCacheData = { list };
@@ -115,7 +115,7 @@ export class SbCache {
     }
 
     /**
-     * Clear {@link cache} and {@link browserStorage} data.
+     * Clear {@link this.cache} and {@link browserStorage} data.
      */
     public async clear(): Promise<void> {
         this.cache.clear();

Extension/src/background/utils/run-info.ts

@@ -65,6 +65,8 @@ async function getData(key: string, fallback = true): Promise<unknown | null> {
 
 /**
  * Get client id from storage.
+ *
+ * @returns Client id or null.
  */
 async function getClientId(): Promise<string | null> {
     const clientId = await getData(CLIENT_ID_KEY);
@@ -78,6 +80,8 @@ async function getClientId(): Promise<string | null> {
 
 /**
  * Get app version from storage.
+ *
+ * @returns App version or null.
  */
 async function getAppVersion(): Promise<string | null> {
     const appVersion = await getData(APP_VERSION_KEY);
@@ -91,6 +95,8 @@ async function getAppVersion(): Promise<string | null> {
 
 /**
  * Get schema version from storage.
+ *
+ * @returns Schema version or 0.
  */
 async function getSchemaVersion(): Promise<number> {
     // don't search schema version in legacy source, because it was added in v4.2
@@ -106,6 +112,8 @@ async function getSchemaVersion(): Promise<number> {
 
 /**
  * Gets app running info from storage.
+ *
+ * @returns App running info.
  */
 export async function getRunInfo(): Promise<RunInfo> {
     const currentAppVersion = Prefs.version;

package.json

@@ -58,7 +58,7 @@
     "eslint-import-resolver-typescript": "^3.5.2",
     "eslint-plugin-import": "^2.26.0",
     "eslint-plugin-import-newlines": "^1.3.0",
-    "eslint-plugin-jsdoc": "^39.3.6",
+    "eslint-plugin-jsdoc": "^50.3.0",
     "eslint-plugin-jsx-a11y": "^6.4.1",
     "eslint-plugin-react": "^7.24.0",
     "eslint-plugin-react-hooks": "^4.2.0",

tools/bundle/size-limit-plugin.js

@@ -35,7 +35,7 @@ export const megabytesToBytes = (mb) => mb * 1024 * 1024;
  */
 export class SizeLimitPlugin {
     /**
-     * @typedef {Object<string, number>} SizeLimits
+     * @typedef {{ [key: string]: number }} SizeLimits
      */
 
     /**