fix jsdocplugin and lint

.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',

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<string>} args — Arguments for scriptlet function.
  * @property {'extension'|'corelibs'} engine — Defines the final form of scriptlet string presentation.

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
  */

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
  */

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

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');

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:

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.
  */

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,

src/helpers/noop-utils.ts

@@ -1,7 +1,5 @@
 /**
  * Noop function
- *
- * @returns undefined
  */
 export const noopFunc: NoopFunc = () => { };
 

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 = (

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,

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) {

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;

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<string>} args Arguments for redirect function
  * @property {'extension'|'test'} [engine] -

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
      */

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;

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

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<string>} 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
  */

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();

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) => {

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) => {