From 1339ca3afb6769399c9ca5e5c4b800195eb58d07 Mon Sep 17 00:00:00 2001 From: stanislav-atr Date: Thu, 15 Jun 2023 01:12:57 +0300 Subject: [PATCH] fix jsdocplugin and lint --- .eslintrc.js | 4 +++- README.md | 2 +- scripts/build-compatibility-table.js | 4 ++-- scripts/build-docs.js | 9 +++------ scripts/build-tests.js | 6 +++--- scripts/check-sources-updates.js | 20 +++++++++++++++++-- scripts/helpers.js | 4 ++-- scripts/test.js | 2 +- src/helpers/get-wildcard-property-in-chain.ts | 1 + src/helpers/noop-utils.ts | 2 -- src/helpers/observer.ts | 2 +- src/helpers/parse-rule.ts | 4 +++- src/helpers/validator.ts | 1 + .../blocking-redirects/click2load.js | 4 ++-- src/redirects/index.js | 2 +- src/redirects/metrika-yandex-tag.js | 2 +- src/redirects/metrika-yandex-watch.js | 2 +- src/redirects/redirects.js | 2 +- src/scriptlets/index.js | 4 ++-- src/scriptlets/m3u-prune.js | 2 +- src/scriptlets/set-constant.js | 6 +++--- src/scriptlets/trusted-set-constant.js | 6 +++--- types/scriptlets.d.ts | 9 +++++++-- types/types.d.ts | 1 - 24 files changed, 61 insertions(+), 40 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 1dfa9642..164c4919 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -14,11 +14,11 @@ module.exports = { }, extends: [ 'airbnb-base', + 'plugin:jsdoc/recommended', ], plugins: [ 'import', 'import-newlines', - 'jsdoc', ], settings: { 'import/resolver': { @@ -75,6 +75,8 @@ module.exports = { 'plugin:@typescript-eslint/recommended', ], rules: { + 'jsdoc/require-param-type': 0, + 'jsdoc/require-returns-type': 0, '@typescript-eslint/ban-ts-comment': 0, '@typescript-eslint/member-delimiter-style': [ 'error', diff --git a/README.md b/README.md index 08b3cdca..41a54100 100644 --- a/README.md +++ b/README.md @@ -214,7 +214,7 @@ where: ```javascript /** - * @typedef {Object} Source — Scriptlet properties. + * @typedef {object} Source — Scriptlet properties. * @property {string} name — Scriptlet name. * @property {Array} args — Arguments for scriptlet function. * @property {'extension'|'corelibs'} engine — Defines the final form of scriptlet string presentation. diff --git a/scripts/build-compatibility-table.js b/scripts/build-compatibility-table.js index 4916b56e..50e230a5 100644 --- a/scripts/build-compatibility-table.js +++ b/scripts/build-compatibility-table.js @@ -20,14 +20,14 @@ const WIKI_COMPATIBILITY_TABLE_PATH = path.resolve( ); /** - * @typedef {Object} CompatibilityItem + * @typedef {object} CompatibilityItem * @property {string} adg AdGuard name * @property {string} abp Adblock Plus name * @property {string} ubo uBlock name */ /** - * @typedef {Object} CompatibilityData + * @typedef {object} CompatibilityData * @property {CompatibilityItem[]} scriptlets list of scriptlets compatibility items * @property {CompatibilityItem[]} redirects list of redirects compatibility items */ diff --git a/scripts/build-docs.js b/scripts/build-docs.js index 07a2fa10..c5ac0117 100644 --- a/scripts/build-docs.js +++ b/scripts/build-docs.js @@ -8,6 +8,7 @@ const { SCRIPTLET_TYPE, TRUSTED_SCRIPTLET_TYPE, REDIRECT_TYPE, + DescribingCommentData, } = require('./helpers'); const { @@ -48,7 +49,7 @@ const aboutTrustedScriptletsPath = path.resolve( /** * Collects required comments from files * - * @returns {Object} describing object for scriptlets and redirects + * @returns {object} describing object for scriptlets and redirects */ const manageDataFromFiles = () => { const dataFromScriptletsFiles = getDataFromFiles( @@ -83,11 +84,7 @@ const manageDataFromFiles = () => { }; /** - * @typedef { import('./helpers').DescribingCommentData } DescribingCommentData - */ - -/** - * @typedef {Object} MarkdownData + * @typedef {object} MarkdownData * @property {string} list table of content * @property {string} body main content which */ diff --git a/scripts/build-tests.js b/scripts/build-tests.js index f5bd86a9..1e5773ac 100644 --- a/scripts/build-tests.js +++ b/scripts/build-tests.js @@ -25,7 +25,7 @@ const MULTIPLE_TEST_FILES_DIRS = [ * * @param {string} fileName test file name * @param {string} subDir subdirectory with test files - * @returns {Object} rollup config + * @returns {object} rollup config */ const getTestConfig = (fileName, subDir) => { if (!fs.existsSync(TESTS_DIST)) { @@ -117,11 +117,11 @@ const getMultipleTestFilesFromDir = (subDir) => { /** * Returns list of rollup configs for tests. * - * @param {Object} limitData Optional data object for limited tests running. If not provided, all tests will be run. + * @param {object} limitData Optional data object for limited tests running. If not provided, all tests will be run. * @param {string} limitData.type Type of tests to run: scriptlets | redirects | helpers | api. * @param {string} limitData.name Optional name scriptlets or redirects test to run. * - * @returns {Object[]} Array of rollup configs for tests. + * @returns {object[]} Array of rollup configs for tests. */ const getTestConfigs = (limitData) => { // run limited list of tests if limitData is provided diff --git a/scripts/check-sources-updates.js b/scripts/check-sources-updates.js index 4ed2aa42..1d4bbd5a 100644 --- a/scripts/check-sources-updates.js +++ b/scripts/check-sources-updates.js @@ -35,7 +35,7 @@ const areArraysOfStringsEqual = (arr1, arr2) => { /** * Returns parsed compatibility table * - * @returns {Object} + * @returns {object} */ const getCompatibilityTable = () => { const rawData = fs.readFileSync(COMPATIBILITY_TABLE_DATA_PATH); @@ -66,7 +66,7 @@ const getRedirectsFromTable = (platform) => { }; /** - * @typedef {Object} Diff + * @typedef {object} Diff * @property {string[]} added added content * @property {string[]} removed removed content */ @@ -145,6 +145,8 @@ const ALIASES_MARKER = 'aliases: '; /** * Make request to UBO repo(master), parses and returns the list of UBO scriptlets + * + * @returns {string[]} ubo scriptlets' names */ async function getCurrentUBOScriptlets() { console.log('Downloading UBO file...'); @@ -211,6 +213,8 @@ async function getCurrentUBOScriptlets() { /** * Check updates for UBO Scriptlets + * + * @returns {Diff|null} diff */ async function checkForUBOScriptletsUpdates() { const oldList = getScriptletsFromTable('ubo'); @@ -236,6 +240,8 @@ const UBO_REDIRECTS_DIRECTORY_FILE = 'https://raw.githubusercontent.com/gorhill/ /** * Make request to UBO repo(master), parses and returns the list of UBO redirects + * + * @returns {string[]} ubo redirects' names */ async function getCurrentUBORedirects() { console.log('Downloading UBO page...'); @@ -263,6 +269,8 @@ async function getCurrentUBORedirects() { /** * Checks updates for UBO redirects + * + * @returns {Diff|null} diff */ async function checkForUBORedirectsUpdates() { const oldList = getRedirectsFromTable('ubo'); @@ -289,6 +297,8 @@ const ABP_SNIPPETS_FILE = 'https://raw.githubusercontent.com/adblockplus/adblock /** * Checks for snippets updates + * + * @returns {string[]} abp snippets' names */ async function getCurrentABPSnippets() { // eslint-disable-line no-unused-vars console.log('Downloading ABP file...'); @@ -310,6 +320,8 @@ async function getCurrentABPSnippets() { // eslint-disable-line no-unused-vars /** * Checks for ABP Snippets updates + * + * @returns {Diff|null} diff */ async function checkForABPScriptletsUpdates() { const oldList = getScriptletsFromTable('abp'); @@ -341,6 +353,8 @@ const ABP_REDIRECTS_FILE_SKIP_START = 'exports.resources = '; /** * Gets ABP redirects + * + * @returns {string[]} abp redirects' names */ async function getCurrentABPRedirects() { console.log('Downloading ABP file...'); @@ -355,6 +369,8 @@ async function getCurrentABPRedirects() { /** * Checks for ABP redirects updates + * + * @returns {Diff|null} diff */ async function checkForABPRedirectsUpdates() { const oldList = getRedirectsFromTable('abp'); diff --git a/scripts/helpers.js b/scripts/helpers.js index 46823cf4..475d400b 100644 --- a/scripts/helpers.js +++ b/scripts/helpers.js @@ -31,7 +31,7 @@ const getFilesList = (relativeDirPath) => { }; /** - * @typedef {Object} CommentTag + * @typedef {object} CommentTag * @property {string} type Tag name, e.g. `@scriptlet`, `@redirect`, `@added`. * @property {string} string Text following the tag name. */ @@ -77,7 +77,7 @@ Please add one OR edit the list of NON_SCRIPTLETS_FILES / NON_REDIRECTS_FILES.`) }; /** - * @typedef {Object} DescribingCommentData + * @typedef {object} DescribingCommentData * * Collected data from jsdoc-type comment for every scriptlet or redirect. * @property {string} type parsed instance tag: diff --git a/scripts/test.js b/scripts/test.js index ec10944b..b068bb23 100644 --- a/scripts/test.js +++ b/scripts/test.js @@ -72,7 +72,7 @@ const buildTasksMap = { * Runs specific scriptlets or redirects tests. * * @param {string} type 'scriptlets' | 'redirects'. - * @param {Object} [options] commander options object where: + * @param {object} [options] commander options object where: * - `name` — string[], list of scriptlets or redirects names; * - `gui` — boolean, flag for run the test in gui mode, requires `options.name` to be set. */ diff --git a/src/helpers/get-wildcard-property-in-chain.ts b/src/helpers/get-wildcard-property-in-chain.ts index 0a60f82a..b9404182 100644 --- a/src/helpers/get-wildcard-property-in-chain.ts +++ b/src/helpers/get-wildcard-property-in-chain.ts @@ -7,6 +7,7 @@ * @param chain chain of owner properties * @param lookThrough should the method look through it's props in order to find wildcard * @param output result acc + * @returns list of ChainInfo objects */ export function getWildcardPropertyInChain( base: ChainBase, diff --git a/src/helpers/noop-utils.ts b/src/helpers/noop-utils.ts index 21a8a5e4..d8abdaef 100644 --- a/src/helpers/noop-utils.ts +++ b/src/helpers/noop-utils.ts @@ -1,7 +1,5 @@ /** * Noop function - * - * @returns undefined */ export const noopFunc: NoopFunc = () => { }; diff --git a/src/helpers/observer.ts b/src/helpers/observer.ts index 0bbbe290..f97f44fc 100644 --- a/src/helpers/observer.ts +++ b/src/helpers/observer.ts @@ -77,7 +77,7 @@ export const getAddedNodes = (mutations: MutationRecord[]): Node[] => { * throttling and disconnect timeout. * * @param {Function} callback MutationObserver callback - * @param {Object} options MutationObserver options + * @param {object} options MutationObserver options * @param timeout Disconnect timeout in ms */ export const observeDocumentWithTimeout = ( diff --git a/src/helpers/parse-rule.ts b/src/helpers/parse-rule.ts index 712fc13a..ca718352 100644 --- a/src/helpers/parse-rule.ts +++ b/src/helpers/parse-rule.ts @@ -117,6 +117,7 @@ export const parseRule = (ruleText: string): ParsedRule => { * @param rule rule string * @param index index * @param Object helper object that contains prop symb with current separator char + * @param Object.sep contains prop `symb` with current separator char * @throws throws if given rule is not a scriptlet * @returns transition */ @@ -157,7 +158,8 @@ export const parseRule = (ruleText: string): ParsedRule => { * @param index index * @param Object helper object * @param Object.sep contains prop `symb` with current separator char - * @param Object.saver helper which allow to save strings by car by char + * @param Object.saver helper which allow to save strings by car by cha + * @returns transition */ const param = ( rule: string, diff --git a/src/helpers/validator.ts b/src/helpers/validator.ts index f8bf69b3..59818ac8 100644 --- a/src/helpers/validator.ts +++ b/src/helpers/validator.ts @@ -148,6 +148,7 @@ const scriptletNameValidationCache = new Map(); * Uses cache for better performance. * * @param name Scriptlet name. + * @returns true if scriptlet name is a valid one. */ const isValidScriptletName = (name: string): boolean => { if (!name) { diff --git a/src/redirects/blocking-redirects/click2load.js b/src/redirects/blocking-redirects/click2load.js index 37301ccc..5cb55b88 100644 --- a/src/redirects/blocking-redirects/click2load.js +++ b/src/redirects/blocking-redirects/click2load.js @@ -29,7 +29,7 @@ function clickToLoad() { * because frame will be shown anyway if click2load redirect rule used * * @param {string} rawQueryStr - * @returns {Object} key is parameter name and value is parameter value + * @returns {object} key is parameter name and value is parameter value */ const parseSearchParam = (rawQueryStr) => { const res = {}; @@ -125,7 +125,7 @@ function clickToLoad() { * Returns translations data for navigator.language * or 'en' if navigator.language is not supported * - * @returns {Object} data for one locale with 'title' and 'button' keys + * @returns {object} data for one locale with 'title' and 'button' keys */ const getTranslations = () => { const baseLocaleData = translationsData.en; diff --git a/src/redirects/index.js b/src/redirects/index.js index c34adb69..d55722b1 100644 --- a/src/redirects/index.js +++ b/src/redirects/index.js @@ -32,7 +32,7 @@ const getRedirectByName = (name) => { }; /** - * @typedef {Object} Source - redirect properties + * @typedef {object} Source - redirect properties * @property {string} name redirect name * @property {Array} args Arguments for redirect function * @property {'extension'|'test'} [engine] - diff --git a/src/redirects/metrika-yandex-tag.js b/src/redirects/metrika-yandex-tag.js index 0b7e7825..38202095 100644 --- a/src/redirects/metrika-yandex-tag.js +++ b/src/redirects/metrika-yandex-tag.js @@ -73,7 +73,7 @@ export function metrikaYandexTag(source) { * * @param {string} id * @param {string} target - * @param {Object} params + * @param {object} params * @param {Function} callback * @param {any} ctx */ diff --git a/src/redirects/metrika-yandex-watch.js b/src/redirects/metrika-yandex-watch.js index 2d10d850..dcedbab2 100644 --- a/src/redirects/metrika-yandex-watch.js +++ b/src/redirects/metrika-yandex-watch.js @@ -21,7 +21,7 @@ export function metrikaYandexWatch(source) { /** * Gets callback and its context from options and call it in async way * - * @param {Object} options Yandex Metrika API options + * @param {object} options Yandex Metrika API options */ const asyncCallbackFromOptions = (options = {}) => { let { callback } = options; diff --git a/src/redirects/redirects.js b/src/redirects/redirects.js index 60cc2246..535fba65 100644 --- a/src/redirects/redirects.js +++ b/src/redirects/redirects.js @@ -10,7 +10,7 @@ import jsYaml from 'js-yaml'; * content: R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw== * } * - * @typedef {Object} Redirect + * @typedef {object} Redirect * @property {string} title resource name * @property {string} comment resource description * @property {string} content encoded resource content diff --git a/src/scriptlets/index.js b/src/scriptlets/index.js index 46584b48..a4e0a401 100644 --- a/src/scriptlets/index.js +++ b/src/scriptlets/index.js @@ -14,7 +14,7 @@ import { import { getScriptletFunction } from '../../tmp/scriptlets-func'; /** - * @typedef {Object} Source Scriptlet properties. + * @typedef {object} Source Scriptlet properties. * @property {string} name Scriptlet name. * @property {Array} args Arguments for scriptlet function. * @property {'extension'|'corelibs'|'test'} engine Defines the final form of scriptlet string presentation. @@ -54,7 +54,7 @@ function getScriptletCode(source) { /** * Scriptlets variable * - * @returns {Object} object with methods: + * @returns {object} object with methods: * `invoke` method receives one argument with `Source` type * `validate` method receives one argument with `String` type */ diff --git a/src/scriptlets/m3u-prune.js b/src/scriptlets/m3u-prune.js index 52b5afa9..e4ba056f 100644 --- a/src/scriptlets/m3u-prune.js +++ b/src/scriptlets/m3u-prune.js @@ -131,7 +131,7 @@ export function m3uPrune(source, propsToRemove, urlToMatch = '') { * * @param {Array} lines * @param {number} i - * @returns {Object} { array, index } + * @returns {object} { array, index } */ const pruneExtinfFromVmapBlock = (lines, i) => { let array = lines.slice(); diff --git a/src/scriptlets/set-constant.js b/src/scriptlets/set-constant.js index c8ab4aae..1d397183 100644 --- a/src/scriptlets/set-constant.js +++ b/src/scriptlets/set-constant.js @@ -249,10 +249,10 @@ export function setConstant(source, property, value, stack = '', valueWrapper = * IMPORTANT! this duplicates corresponding func in trusted-set-constant scriptlet as * reorganizing this to common helpers will most definitely complicate debugging * - * @param {Object} base arbitrary reachable object + * @param {object} base arbitrary reachable object * @param {string} prop property name * @param {boolean} configurable if set property should be configurable - * @param {Object} handler custom property descriptor object + * @param {object} handler custom property descriptor object * @returns {boolean} true if prop was trapped successfully */ const trapProp = (base, prop, configurable, handler) => { @@ -299,7 +299,7 @@ export function setConstant(source, property, value, stack = '', valueWrapper = * IMPORTANT! this duplicates corresponding func in trusted-set-constant scriptlet as * reorganizing this to common helpers will most definitely complicate debugging * - * @param {Object} owner object that owns chain + * @param {object} owner object that owns chain * @param {string} property chain of owner properties */ const setChainPropAccess = (owner, property) => { diff --git a/src/scriptlets/trusted-set-constant.js b/src/scriptlets/trusted-set-constant.js index 75590bae..b54944fb 100644 --- a/src/scriptlets/trusted-set-constant.js +++ b/src/scriptlets/trusted-set-constant.js @@ -120,10 +120,10 @@ export function trustedSetConstant(source, property, value, stack) { * IMPORTANT! this duplicates corresponding func in set-constant scriptlet as * reorganizing this to common helpers will most definitely complicate debugging * - * @param {Object} base arbitrary reachable object + * @param {object} base arbitrary reachable object * @param {string} prop property name * @param {boolean} configurable if set property should be configurable - * @param {Object} handler custom property descriptor object + * @param {object} handler custom property descriptor object * @returns {boolean} true if prop was trapped successfully */ const trapProp = (base, prop, configurable, handler) => { @@ -170,7 +170,7 @@ export function trustedSetConstant(source, property, value, stack) { * IMPORTANT! this duplicates corresponding func in set-constant scriptlet as * reorganizing this to common helpers will most definitely complicate debugging * - * @param {Object} owner object that owns chain + * @param {object} owner object that owns chain * @param {string} property chain of owner properties */ const setChainPropAccess = (owner, property) => { diff --git a/types/scriptlets.d.ts b/types/scriptlets.d.ts index 793d928b..ec718fb6 100644 --- a/types/scriptlets.d.ts +++ b/types/scriptlets.d.ts @@ -106,7 +106,7 @@ declare module '@adguard/scriptlets' { * @returns Array of AdGuard scriptlet rules: one array item for ADG and UBO or few items for ABP. * For the ADG `rule`, validates its syntax and returns an empty array if it is invalid. */ - function convertScriptletToAdg(ruleText: string): string[]; + function convertScriptletToAdg(rule: string): string[]; /** * 1. For ADG scriptlet checks whether the scriptlet syntax and name are valid. @@ -129,7 +129,7 @@ declare module '@adguard/scriptlets' { * @param {string} name Scriptlet name. * @returns {boolean} True if scriptlet name is valid. */ - function isValidScriptletName(rule: string): boolean; + function isValidScriptletName(name: string): boolean; /** * Returns scriptlet function by `name`. @@ -151,6 +151,7 @@ declare module '@adguard/scriptlets' { /** * Returns filename with extension for requested alias + * * @param alias alias for redirect filename */ getRedirectFilename(alias: string): string; @@ -164,24 +165,28 @@ declare module '@adguard/scriptlets' { /** * Checks if the `rule` is **valid** AdGuard redirect resource rule + * * @param rule */ isValidAdgRedirectRule(rule: string): boolean; /** * Checks if the Ubo redirect `rule` has AdGuard analog. Needed for Ubo->Adg conversion + * * @param rule */ isUboRedirectCompatibleWithAdg(rule: string): boolean; /** * Checks if the Abp redirect `rule` has AdGuard analog. Needed for Abp->Adg conversion + * * @param rule */ isAbpRedirectCompatibleWithAdg(rule: string): boolean; /** * Converts redirect rule to AdGuard one + * * @param rule */ convertRedirectToAdg(rule: string): string; diff --git a/types/types.d.ts b/types/types.d.ts index 2aa51163..6a29bcb2 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -8,7 +8,6 @@ interface Source { domainName?: string; } -type ValueOf = T[keyof T]; type ArbitraryObject = { [key: string | symbol | number]: unknown }; type ArbitraryFunction = (...args: unknown[]) => unknown; type NoopFunc = () => void;