diff --git a/.eslintrc.js b/.eslintrc.js index 64f044c5..2a804dba 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -31,8 +31,6 @@ module.exports = { 'no-restricted-syntax': 0, // jsdoc rules 'jsdoc/check-tag-names': ['error', { definedTags: ['scriptlet', 'trustedScriptlet', 'redirect'] }], - 'jsdoc/require-returns-description': 0, - 'jsdoc/newline-after-description': 0, 'jsdoc/require-param': 0, 'jsdoc/tag-lines': 0, 'jsdoc/require-jsdoc': 0, @@ -42,6 +40,8 @@ module.exports = { // jsdoc problematics 'jsdoc/valid-types': 0, 'jsdoc/no-undefined-types': 0, + // jsdoc questionable + 'jsdoc/require-returns-description': 0, }, overrides: [ { diff --git a/scripts/build-compatibility-table.js b/scripts/build-compatibility-table.js index 72c70163..f3605252 100644 --- a/scripts/build-compatibility-table.js +++ b/scripts/build-compatibility-table.js @@ -77,6 +77,7 @@ const getTableHeader = () => { /** * Builds markdown string of scriptlets/redirect compatibility table + * * @param {string} title title for scriptlets or redirects * @param {CompatibilityItem[]} data array of scriptlets or redirects compatibility data items * @param {'scriptlets'|'redirects'} id diff --git a/scripts/build-redirects.js b/scripts/build-redirects.js index dee2abc6..ab294146 100644 --- a/scripts/build-redirects.js +++ b/scripts/build-redirects.js @@ -143,6 +143,7 @@ const getJsRedirects = async (options = {}) => { // TODO: seems like duplicate of already existed code /** * Returns first line of describing comment from redirect resource file + * * @param {string} rrName redirect resource name */ const getComment = (rrName) => { diff --git a/scripts/build-tests.js b/scripts/build-tests.js index d75871f9..bc6ba8fe 100644 --- a/scripts/build-tests.js +++ b/scripts/build-tests.js @@ -14,6 +14,7 @@ const TEST_FILE_NAME_MARKER = '.test.js'; /** * Prepares rollup config for test file + * * @param {string} fileName test file name * @param {string} dirPath resolved directory path * @param {string} subDir subdirectory with test files diff --git a/scripts/check-sources-updates.js b/scripts/check-sources-updates.js index 99fe8940..4074872d 100644 --- a/scripts/check-sources-updates.js +++ b/scripts/check-sources-updates.js @@ -14,6 +14,7 @@ const { /** * Checks if arrays contain the same strings + * * @param {Array} arr1 * @param {Array} arr2 */ @@ -39,6 +40,7 @@ const getCompatibilityTable = () => { /** * Returns list of scriptlets listed in table for specified platform + * * @param {"ubo"|"abp"} platform */ const getScriptletsFromTable = (platform) => { @@ -48,6 +50,7 @@ const getScriptletsFromTable = (platform) => { /** * Returns list of redirects listed in table for specified platform + * * @param {"ubo"|"abp"} platform */ const getRedirectsFromTable = (platform) => { @@ -57,6 +60,7 @@ const getRedirectsFromTable = (platform) => { /** * Finds a difference between old and new array + * * @param {Array} oldList * @param {Array} newList */ @@ -77,6 +81,7 @@ const getDiff = (oldList, newList) => { /** * Marks removed rules with (removed) and adds new rules to the end of the table + * * @param {{removed: Array, added: Array}} diff Object with diffs for certain type and platform * @param {"scriptlets"|"redirects"} ruleType * @param {"ubo"|"abp"} platform diff --git a/scripts/helpers.js b/scripts/helpers.js index d4a01c56..9549d374 100644 --- a/scripts/helpers.js +++ b/scripts/helpers.js @@ -21,6 +21,7 @@ const writeFile = async (filePath, content) => { /** * Gets list of `.js` files in directory + * * @param {string} relativeDirPath relative path to directory * @returns {string[]} array of file names */ @@ -108,6 +109,7 @@ const prepareCommentsData = (commentTags, source) => { /** * Gets data objects which describe every required comment in one directory + * * @param {string[]} filesList list of files in directory * @param {string} relativeDirPath relative path to directory * diff --git a/scripts/rollup-runners.js b/scripts/rollup-runners.js index 776e2f6c..61e4d976 100644 --- a/scripts/rollup-runners.js +++ b/scripts/rollup-runners.js @@ -5,6 +5,7 @@ const { log } = console; /** * Builds scriptlets + * * @param {object|object[]} config config may be list of configs or one config */ export const rollupStandard = async (config) => { @@ -26,6 +27,7 @@ export const rollupStandard = async (config) => { /** * Builds scriptlets in the watch mode + * * @param {object|object[]} config - config may be list of configs or one config */ export const rollupWatch = (config) => { diff --git a/src/helpers/add-event-listener-utils.js b/src/helpers/add-event-listener-utils.js index c579dca5..51f93ea6 100644 --- a/src/helpers/add-event-listener-utils.js +++ b/src/helpers/add-event-listener-utils.js @@ -1,5 +1,6 @@ /** * Validates event type + * * @param {*} type * @returns {boolean} */ @@ -10,6 +11,7 @@ export const validateType = (type) => { /** * Validates event listener + * * @param {*} listener * @returns {boolean} */ @@ -26,6 +28,7 @@ export const validateListener = (listener) => { /** * Serialize valid event listener * https://developer.mozilla.org/en-US/docs/Web/API/EventListener + * * @param {EventListener} listener valid listener * @returns {string} */ diff --git a/src/helpers/adjust-set-utils.js b/src/helpers/adjust-set-utils.js index 791b7b1e..39e35dc1 100644 --- a/src/helpers/adjust-set-utils.js +++ b/src/helpers/adjust-set-utils.js @@ -4,6 +4,7 @@ export const shouldMatchAnyDelay = (delay) => delay === '*'; /** * Handles input delay value + * * @param {*} delay * @returns {number} proper number delay value */ @@ -18,6 +19,7 @@ export const getMatchDelay = (delay) => { /** * Checks delay match condition + * * @param {*} inputDelay * @param {number} realDelay * @returns {boolean} @@ -29,6 +31,7 @@ export const isDelayMatched = (inputDelay, realDelay) => { /** * Handles input boost value + * * @param {*} boost * @returns {number} proper number boost multiplier value */ diff --git a/src/helpers/array-utils.js b/src/helpers/array-utils.js index 371e4266..33a37fe3 100644 --- a/src/helpers/array-utils.js +++ b/src/helpers/array-utils.js @@ -2,6 +2,7 @@ * Some browsers do not support Array.prototype.flat() * for example, Opera 42 which is used for browserstack tests * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat + * * @param {Array} input */ export const flatten = (input) => { @@ -24,6 +25,7 @@ export const flatten = (input) => { /** * Predicate method to check if the array item exists + * * @param {any} item * @returns {boolean} */ diff --git a/src/helpers/converter.js b/src/helpers/converter.js index ba0dc899..940c360e 100644 --- a/src/helpers/converter.js +++ b/src/helpers/converter.js @@ -66,6 +66,7 @@ const REMOVE_ATTR_CLASS_APPLYING = ['asap', 'stay', 'complete']; /** * Returns array of strings separated by space which not in quotes + * * @param {string} str */ const getSentences = (str) => { @@ -75,6 +76,7 @@ const getSentences = (str) => { /** * Replaces string with data by placeholders + * * @param {string} str * @param {object} data - where keys are placeholders names */ @@ -104,6 +106,7 @@ const splitArgs = (str) => { /** * Validates remove-attr/class scriptlet args + * * @param {string[]} parsedArgs * @returns {string[]|Error} valid args OR error for invalid selector */ @@ -147,6 +150,7 @@ const validateRemoveAttrClassArgs = (parsedArgs) => { /** * Converts string of UBO scriptlet rule to AdGuard scriptlet rule + * * @param {string} rule - UBO scriptlet rule * @returns {string[]} - array with one AdGuard scriptlet rule */ @@ -193,6 +197,7 @@ export const convertUboScriptletToAdg = (rule) => { /** * Convert string of ABP snippet rule to AdGuard scriptlet rule + * * @param {string} rule - ABP snippet rule * @returns {Array} - array of AdGuard scriptlet rules - * one or few items depends on Abp-rule @@ -221,6 +226,7 @@ export const convertAbpSnippetToAdg = (rule) => { /** * Converts scriptlet rule to AdGuard one + * * @param {string} rule * @returns {Array} - array of AdGuard scriptlet rules - * one item for Adg and Ubo or few items for Abp @@ -240,6 +246,7 @@ export const convertScriptletToAdg = (rule) => { /** * Converts UBO scriptlet rule to AdGuard one + * * @param {string} rule - AdGuard scriptlet rule * @returns {string} - UBO scriptlet rule */ @@ -328,6 +335,7 @@ export const convertAdgScriptletToUbo = (rule) => { /** * Checks whether the ADG scriptlet exists or UBO/ABP scriptlet is compatible to ADG + * * @param {string} input - can be ADG or UBO or ABP scriptlet rule * @returns {boolean} */ @@ -350,6 +358,7 @@ export const isValidScriptletRule = (input) => { /** * Gets index and redirect resource marker from UBO/ADG modifiers array + * * @param {string[]} modifiers * @param {object} redirectsData validator.REDIRECT_RULE_TYPES.(UBO|ADG) * @param {string} rule @@ -373,6 +382,7 @@ const getMarkerData = (modifiers, redirectsData, rule) => { /** * Converts Ubo redirect rule to Adg one + * * @param {string} rule * @returns {string} */ @@ -403,6 +413,7 @@ export const convertUboRedirectToAdg = (rule) => { /** * Converts Abp redirect rule to Adg one + * * @param {string} rule * @returns {string} */ @@ -428,6 +439,7 @@ export const convertAbpRedirectToAdg = (rule) => { /** * Converts redirect rule to AdGuard one + * * @param {string} rule * @returns {string} */ @@ -452,6 +464,7 @@ export const convertRedirectToAdg = (rule) => { * Source types are chosen according to redirect name * e.g. ||ad.com^$redirect=,important ->> ||ad.com^$redirect=,important,script * 3. Replaces Adg redirect name by Ubo analog + * * @param {string} rule * @returns {string} */ diff --git a/src/helpers/cookie-utils.js b/src/helpers/cookie-utils.js index 4ea3dd14..338a4ec1 100644 --- a/src/helpers/cookie-utils.js +++ b/src/helpers/cookie-utils.js @@ -94,6 +94,7 @@ export const getLimitedCookieValue = (value) => { /** * Parses cookie string into object + * * @param {string} cookieString string that conforms to document.cookie format * @returns {object} key:value object that corresponds with incoming cookies keys and values */ @@ -124,6 +125,7 @@ export const parseCookieString = (cookieString) => { /** * Check if cookie with specified name and value is present in a cookie string + * * @param {string} cookieString * @param {string} name * @param {string} value diff --git a/src/helpers/create-on-error-handler.js b/src/helpers/create-on-error-handler.js index f298d2ce..50118461 100644 --- a/src/helpers/create-on-error-handler.js +++ b/src/helpers/create-on-error-handler.js @@ -1,6 +1,7 @@ /** * Generates function which silents global errors on page generated by scriptlet * If error doesn't belong to our error we transfer it to the native onError handler + * * @param {string} rid - unique identifier of scriptlet * @returns {onError} */ diff --git a/src/helpers/hit.js b/src/helpers/hit.js index 810216ef..2c766c34 100644 --- a/src/helpers/hit.js +++ b/src/helpers/hit.js @@ -1,6 +1,7 @@ /* eslint-disable no-console, no-underscore-dangle */ /** * Hit used only for debug purposes now + * * @param {Source} source * use LOG_MARKER = 'log: ' at the start of a message * for logging scriptlets diff --git a/src/helpers/injector.js b/src/helpers/injector.js index d90bfd6c..742f0267 100644 --- a/src/helpers/injector.js +++ b/src/helpers/injector.js @@ -1,5 +1,6 @@ /** * Concat dependencies to scriptlet code + * * @param {string} scriptlet string view of scriptlet */ export function attachDependencies(scriptlet) { @@ -11,6 +12,7 @@ export function attachDependencies(scriptlet) { /** * Add scriptlet call to existing code + * * @param {Function} scriptlet * @param {string} code */ @@ -64,6 +66,7 @@ export function passSourceAndProps(source, code, redirect = false) { /** * Wrap code in no name function + * * @param {string} code which must be wrapped */ export function wrapInNonameFunc(code) { diff --git a/src/helpers/log-message.js b/src/helpers/log-message.js index 59504576..655fbb6a 100644 --- a/src/helpers/log-message.js +++ b/src/helpers/log-message.js @@ -7,6 +7,7 @@ * Convention is to log messages by source.verbose if such log * is not a part of scriptlet's functionality, eg on invalid input, * and use 'forced' argument otherwise. + * * @param {Source} source required * @param {string} message required, message to log * @param {boolean} [forced=false] to log message unconditionally diff --git a/src/helpers/match-request-props.js b/src/helpers/match-request-props.js index cb582db3..54503490 100644 --- a/src/helpers/match-request-props.js +++ b/src/helpers/match-request-props.js @@ -13,6 +13,7 @@ import { logMessage } from './log-message'; * Checks if given propsToMatch string matches with given request data * This is used by prevent-xhr, prevent-fetch, trusted-replace-xhr-response * and trusted-replace-fetch-response scriptlets + * * @param {Source} source * @param {string} propsToMatch * @param {object} requestData object with standard properties of fetch/xhr like url, method etc diff --git a/src/helpers/match-stack.js b/src/helpers/match-stack.js index 457e0ce8..4be0ca81 100644 --- a/src/helpers/match-stack.js +++ b/src/helpers/match-stack.js @@ -5,6 +5,7 @@ import { getNativeRegexpTest } from './regexp-utils'; /** * Checks if the stackTrace contains stackRegexp * https://github.com/AdguardTeam/Scriptlets/issues/82 + * * @param {string|undefined} stackMatch - input stack value to match * @param {string} stackTrace - script error stack trace * @returns {boolean} diff --git a/src/helpers/noop-utils.js b/src/helpers/noop-utils.js index 2c997d47..4fc2c139 100644 --- a/src/helpers/noop-utils.js +++ b/src/helpers/noop-utils.js @@ -1,23 +1,27 @@ /** * Noop function + * * @returns {undefined} undefined */ export const noopFunc = () => { }; /** * Function returns null + * * @returns {null} null */ export const noopNull = () => null; /** * Function returns true + * * @returns {boolean} true */ export const trueFunc = () => true; /** * Function returns false + * * @returns {boolean} false */ export const falseFunc = () => false; @@ -31,18 +35,21 @@ export function noopThis() { /** * Function returns empty string + * * @returns {string} empty string */ export const noopStr = () => ''; /** * Function returns empty array + * * @returns {Array} empty array */ export const noopArray = () => []; /** * Function returns empty object + * * @returns {object} empty object */ export const noopObject = () => ({}); @@ -54,6 +61,7 @@ export const noopPromiseReject = () => Promise.reject(); // eslint-disable-line /** * Returns Promise object that is resolved with specified props + * * @param {string} [responseBody='{}'] * @param {string} [responseUrl=''] * @param {string} [responseType='default'] diff --git a/src/helpers/number-utils.js b/src/helpers/number-utils.js index 72b50db7..c008986f 100644 --- a/src/helpers/number-utils.js +++ b/src/helpers/number-utils.js @@ -1,6 +1,7 @@ /** * Determines whether the passed value is NaN * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isNaN + * * @param {*} num * @returns {boolean} */ @@ -13,6 +14,7 @@ export const nativeIsNaN = (num) => { /** * Determines whether the passed value is a finite number * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isFinite + * * @param {*} num * @returns {boolean} */ @@ -24,6 +26,7 @@ export const nativeIsFinite = (num) => { /** * Parses string for a number, if possible, otherwise returns null. + * * @param {*} rawString * @returns {number|null} */ @@ -38,6 +41,7 @@ export const getNumberFromString = (rawString) => { /** * Generate a random integer between two values, inclusive * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random#getting_a_random_integer_between_two_values_inclusive + * * @param {number} min * @param {number} max * @returns {number} diff --git a/src/helpers/object-utils.js b/src/helpers/object-utils.js index a0e42a93..decba50a 100644 --- a/src/helpers/object-utils.js +++ b/src/helpers/object-utils.js @@ -2,6 +2,7 @@ * Converts object to array of pairs. * Object.entries() polyfill because it is not supported by IE * https://caniuse.com/?search=Object.entries + * * @param {object} object * @returns {Array} array of pairs */ @@ -16,6 +17,7 @@ export const getObjectEntries = (object) => { * Converts array of pairs to object. * Object.fromEntries() polyfill because it is not supported by IE * https://caniuse.com/?search=Object.fromEntries + * * @param {Array} entries - array of pairs * @returns {object} */ @@ -32,6 +34,7 @@ export const getObjectFromEntries = (entries) => { /** * Checks whether the obj is an empty object + * * @param {object} obj * @returns {boolean} */ @@ -39,6 +42,7 @@ export const isEmptyObject = (obj) => Object.keys(obj).length === 0 && !obj.prot /** * Checks whether the obj is an empty object + * * @param {object} obj * @param {string} prop * @returns {object | null} @@ -53,6 +57,7 @@ export const safeGetDescriptor = (obj, prop) => { /** * Set getter and setter to property if it's configurable + * * @param {object} object target object with property * @param {string} property property name * @param {PropertyDescriptor} descriptor contains getter and setter functions diff --git a/src/helpers/observer.js b/src/helpers/observer.js index a8f4d129..e3229fe2 100644 --- a/src/helpers/observer.js +++ b/src/helpers/observer.js @@ -2,6 +2,7 @@ import { throttle } from './throttle'; /** * DOM tree changes observer. Used for 'remove-attr' and 'remove-class' scriptlets + * * @param {Function} callback * @param {boolean} observeAttrs - optional parameter - should observer check attributes changes */ diff --git a/src/helpers/open-shadow-dom-utils.js b/src/helpers/open-shadow-dom-utils.js index 0760c70f..3a5f314c 100644 --- a/src/helpers/open-shadow-dom-utils.js +++ b/src/helpers/open-shadow-dom-utils.js @@ -2,6 +2,7 @@ import { flatten } from './array-utils'; /** * Finds shadow-dom host (elements with shadowRoot property) in DOM of rootElement. + * * @param {HTMLElement} rootElement * @returns {HTMLElement[]} shadow-dom hosts */ @@ -37,6 +38,7 @@ export const findHostElements = (rootElement) => { * Pierces open shadow-dom in order to find: * - elements by 'selector' matching * - inner shadow-dom hosts + * * @param {string} selector * @param {HTMLElement[]|external:NodeList} hostElements * @returns {PierceData} diff --git a/src/helpers/parse-flags.js b/src/helpers/parse-flags.js index 6e80fa98..76927876 100644 --- a/src/helpers/parse-flags.js +++ b/src/helpers/parse-flags.js @@ -1,5 +1,6 @@ /** * Behaviour flags string parser + * * @param {string} flags required, 'applying' argument string * @returns {object} */ diff --git a/src/helpers/parse-rule.js b/src/helpers/parse-rule.js index 31c29968..b704a2cf 100644 --- a/src/helpers/parse-rule.js +++ b/src/helpers/parse-rule.js @@ -1,5 +1,6 @@ /** * Iterate over iterable argument and evaluate current state with transitions + * * @param {Array|Collection|string} iterable * @param {object} transitions transtion functions * @param {string} init first transition name @@ -47,6 +48,7 @@ const substringAfter = (str, separator) => { /** * Parse and validate scriptlet rule + * * @param {*} ruleText * @returns {{name: string, args: Array}} */ @@ -63,6 +65,7 @@ export const parseRule = (ruleText) => { /** * Transition function: the current index position in start, end or between params + * * @param {string} rule * @param {number} index * @param {object} Object @@ -99,6 +102,7 @@ export const parseRule = (ruleText) => { }; /** * Transition function: the current index position inside param + * * @param {string} rule * @param {number} index * @param {object} Object diff --git a/src/helpers/prevent-utils.js b/src/helpers/prevent-utils.js index 0dc0fb41..7b79009c 100644 --- a/src/helpers/prevent-utils.js +++ b/src/helpers/prevent-utils.js @@ -7,6 +7,7 @@ import { /** * Checks whether the passed arg is proper callback + * * @param {*} callback * @returns {boolean} */ @@ -22,6 +23,7 @@ export const isValidCallback = (callback) => { * Checks whether 'callback' and 'delay' are matching * by given parameters 'matchCallback' and 'matchDelay'. * Used for prevent-setTimeout and prevent-setInterval. + * * @param {object} preventData * @param {Function} preventData.callback * @param {any} preventData.delay diff --git a/src/helpers/request-utils.js b/src/helpers/request-utils.js index 6b80cef8..bbd1f324 100644 --- a/src/helpers/request-utils.js +++ b/src/helpers/request-utils.js @@ -4,6 +4,7 @@ import { getObjectFromEntries } from './object-utils'; /** * Returns array of request props that are supported by fetch/xhr scriptlets. * Includes common 'url' and 'method' props and all other fetch-specific props + * * @returns {string[]} */ export const getRequestProps = () => [ @@ -24,6 +25,7 @@ export const getRequestProps = () => [ /** * Collects Request options to object + * * @param {Request} request * @returns {object} data object */ @@ -40,6 +42,7 @@ export const getRequestData = (request) => { /** * Collects fetch args to object + * * @param {*} args fetch args * @returns {object} data object */ @@ -70,6 +73,7 @@ export const getFetchData = (args) => { /** * Collect xhr.open arguments to object + * * @param {string} method * @param {string} url * @param {string} async @@ -90,6 +94,7 @@ export const getXhrData = (method, url, async, user, password) => { /** * Parse propsToMatch input string into object; * used for prevent-fetch and prevent-xhr + * * @param {string} propsToMatchStr * @returns {object} object where 'key' is prop name and 'value' is prop value */ @@ -123,6 +128,7 @@ export const parseMatchProps = (propsToMatchStr) => { /** * Validates parsed data values + * * @param {object} data * @returns {boolean} */ @@ -133,6 +139,7 @@ export const validateParsedData = (data) => { /** * Converts valid parsed data to data obj for further matching + * * @param {object} data * @returns {object} */ diff --git a/src/helpers/script-source-utils.js b/src/helpers/script-source-utils.js index 740659da..6048c916 100644 --- a/src/helpers/script-source-utils.js +++ b/src/helpers/script-source-utils.js @@ -4,6 +4,7 @@ import { startsWith } from './string-utils'; * Determines if type of script is inline or injected * and when it's one of them then return true, otherwise false * https://github.com/AdguardTeam/Scriptlets/issues/201 + * * @param {string|undefined} stackMatch - input stack value to match * @param {string} stackTrace - script error stack trace * @returns {boolean} diff --git a/src/helpers/storage-utils.js b/src/helpers/storage-utils.js index d88e443b..51a51774 100644 --- a/src/helpers/storage-utils.js +++ b/src/helpers/storage-utils.js @@ -7,6 +7,7 @@ import { logMessage } from './log-message'; /** * Sets item to a specified storage, if storage isn't full. + * * @param {Source} source * @param {Storage} storage storage instance to set item into * @param {string} key @@ -24,6 +25,7 @@ export const setStorageItem = (source, storage, key, value) => { /** * Gets supported storage item value + * * @param {string} value input item value * @returns {string|null|undefined|boolean} valid item value if ok OR null if not */ diff --git a/src/helpers/string-utils.js b/src/helpers/string-utils.js index 298d6f06..8b4087c0 100644 --- a/src/helpers/string-utils.js +++ b/src/helpers/string-utils.js @@ -8,6 +8,7 @@ import { /** * String.prototype.replaceAll polyfill + * * @param {string} input input string * @param {string} substr to look for * @param {string} newSubstr replacement @@ -17,6 +18,7 @@ export const replaceAll = (input, substr, newSubstr) => input.split(substr).join /** * Escapes special chars in string + * * @param {string} str * @returns {string} */ @@ -25,12 +27,14 @@ export const escapeRegExp = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); /** * A literal string or regexp pattern wrapped in forward slashes. * For example, 'simpleStr' or '/adblock|_0x/'. + * * @typedef {string} RawStrPattern */ /** * Converts string to the regexp * TODO think about nested dependencies, but be careful with dependency loops + * * @param {RawStrPattern} [input=''] literal string or regexp pattern; defaults to '' (empty string) * @returns {RegExp} regular expression; defaults to /.?/ * @throws {SyntaxError} Throw an error for invalid regex pattern @@ -50,6 +54,7 @@ export const toRegExp = (input = '') => { /** * Checks whether the input string can be converted to regexp + * * @param {RawStrPattern} input literal string or regexp pattern * @returns {boolean} */ @@ -72,6 +77,7 @@ export const isValidStrPattern = (input) => { /** * Get string before regexp first match + * * @param {string} str * @param {RegExp} rx */ @@ -82,6 +88,7 @@ export const getBeforeRegExp = (str, rx) => { /** * Checks whether the string starts with the substring + * * @param {string} str full string * @param {string} prefix substring * @returns {boolean} @@ -94,6 +101,7 @@ export const startsWith = (str, prefix) => { /** * Checks whether the string ends with the substring + * * @param {string} str full string * @param {string} ending substring * @returns {boolean} @@ -122,6 +130,7 @@ export const substringBefore = (str, separator) => { /** * Wrap str in single quotes and replaces single quotes to double one + * * @param {string} str */ export const wrapInSingleQuotes = (str) => { @@ -137,6 +146,7 @@ export const wrapInSingleQuotes = (str) => { /** * Returns substring enclosed in the widest braces + * * @param {string} str */ export const getStringInBraces = (str) => { @@ -147,6 +157,7 @@ export const getStringInBraces = (str) => { /** * Prepares RTCPeerConnection config as string for proper logging + * * @param {*} config * @returns {string} stringified config */ @@ -178,6 +189,7 @@ export const convertRtcConfigToString = (config) => { /** * Checks whether the match input string can be converted to regexp, * used for match inputs with possible negation + * * @param {string} match literal string or regexp pattern * @returns {boolean} */ @@ -193,6 +205,7 @@ export const isValidMatchStr = (match) => { /** * Validates the match input number, * used for match inputs with possible negation + * * @param {string} match string of match number * @returns {boolean} */ @@ -216,6 +229,7 @@ export const isValidMatchNumber = (match) => { * Parses match arg with possible negation for no matching. * Needed for prevent-setTimeout, prevent-setInterval, * prevent-requestAnimationFrame and prevent-window-open + * * @param {string} match * @returns {MatchData} */ @@ -236,6 +250,7 @@ export const parseMatchArg = (match) => { /** * Parses delay arg with possible negation for no matching. * Needed for prevent-setTimeout and prevent-setInterval + * * @param {string} delay * @returns {DelayData} `{ isInvertedDelayMatch, delayMatch }` where: * `isInvertedDelayMatch` is boolean, @@ -252,6 +267,7 @@ export const parseDelayArg = (delay) => { /** * Converts object to string for logging + * * @param {object} obj data object * @returns {string} */ @@ -273,6 +289,7 @@ export const objectToString = (obj) => { /** * Converts types into a string + * * @param {*} value * @returns {string} */ @@ -295,6 +312,7 @@ export const convertTypeToString = (value) => { /** * Generate a random string, a length of the string is provided as an argument + * * @param {number} length * @returns {string} */ @@ -310,6 +328,7 @@ export function getRandomStrByLength(length) { /** * Generate a random string + * * @param {string} customResponseText * @returns {string|null} random string or null if passed argument is invalid */ diff --git a/src/helpers/throttle.js b/src/helpers/throttle.js index 02bcfb96..fd984e56 100644 --- a/src/helpers/throttle.js +++ b/src/helpers/throttle.js @@ -1,6 +1,7 @@ /** * Returns a wrapper, passing the call to 'method' at maximum once per 'delay' milliseconds. * Those calls that fall into the "cooldown" period, are ignored + * * @param {Function} cb * @param {number} delay - milliseconds */ diff --git a/src/helpers/validator.js b/src/helpers/validator.js index 364b7557..0175642a 100644 --- a/src/helpers/validator.js +++ b/src/helpers/validator.js @@ -18,6 +18,7 @@ const COMMENT_MARKER = '!'; /** * Checks if rule text is comment e.g. !!example.org##+js(set-constant.js, test, false) + * * @param {string} rule * @returns {boolean} */ @@ -51,6 +52,7 @@ const ADG_CSS_MASK_REG = /#@?\$#.+?\s*\{.*\}\s*$/g; /** * Checks if the `rule` is AdGuard scriptlet rule + * * @param {string} rule - rule text */ const isAdgScriptletRule = (rule) => { @@ -62,6 +64,7 @@ const isAdgScriptletRule = (rule) => { /** * Checks if the `rule` is uBO scriptlet rule + * * @param {string} rule rule text */ const isUboScriptletRule = (rule) => { @@ -77,6 +80,7 @@ const isUboScriptletRule = (rule) => { /** * Checks if the `rule` is AdBlock Plus snippet + * * @param {string} rule rule text */ const isAbpSnippetRule = (rule) => { @@ -90,6 +94,7 @@ const isAbpSnippetRule = (rule) => { /** * Finds scriptlet by it's name + * * @param {string} name - scriptlet name */ const getScriptletByName = (name) => { @@ -107,6 +112,7 @@ const getScriptletByName = (name) => { /** * Checks if the scriptlet name is valid + * * @param {string} name - Scriptlet name */ const isValidScriptletName = (name) => { @@ -260,6 +266,7 @@ const REDIRECT_RULE_TYPES = { /** * Parses redirect rule modifiers + * * @param {string} rule * @returns {Array} */ @@ -267,6 +274,7 @@ const parseModifiers = (rule) => substringAfter(rule, '$').split(','); /** * Gets redirect resource name + * * @param {string} rule * @param {string} marker - specific Adg/Ubo or Abp redirect resources marker * @returns {string} - redirect resource name @@ -281,6 +289,7 @@ const getRedirectName = (rule, marker) => { /** * Checks if the `rule` is AdGuard redirect rule. * Discards comments and JS rules and checks if the `rule` has 'redirect' modifier. + * * @param {string} rule - rule text */ const isAdgRedirectRule = (rule) => { @@ -300,6 +309,7 @@ const isAdgRedirectRule = (rule) => { /** * Checks if the `rule` satisfies the `type` + * * @param {string} rule - rule text * @param {'VALID_ADG'|'ADG'|'UBO'|'ABP'} type - type of a redirect rule */ @@ -341,6 +351,7 @@ const isRedirectRuleByType = (rule, type) => { /** * Checks if the `rule` is **valid** AdGuard redirect resource rule + * * @param {string} rule - rule text * @returns {boolean} */ @@ -350,6 +361,7 @@ const isValidAdgRedirectRule = (rule) => { /** * Checks if the AdGuard redirect `rule` has Ubo analog. Needed for Adg->Ubo conversion + * * @param {string} rule - AdGuard rule text * @returns {boolean} - true if the rule can be converted to Ubo */ @@ -359,6 +371,7 @@ const isAdgRedirectCompatibleWithUbo = (rule) => { /** * Checks if the Ubo redirect `rule` has AdGuard analog. Needed for Ubo->Adg conversion + * * @param {string} rule - Ubo rule text * @returns {boolean} - true if the rule can be converted to AdGuard */ @@ -368,6 +381,7 @@ const isUboRedirectCompatibleWithAdg = (rule) => { /** * Checks if the Abp redirect `rule` has AdGuard analog. Needed for Abp->Adg conversion + * * @param {string} rule - Abp rule text * @returns {boolean} - true if the rule can be converted to AdGuard */ diff --git a/src/redirects/blocking-redirects/click2load.js b/src/redirects/blocking-redirects/click2load.js index d63093c4..ee5545b4 100644 --- a/src/redirects/blocking-redirects/click2load.js +++ b/src/redirects/blocking-redirects/click2load.js @@ -27,6 +27,7 @@ function clickToLoad() { * Some browsers does not support URL.searchParams.get() * but we need script run with no error * 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 */ @@ -123,6 +124,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 */ const getTranslations = () => { @@ -150,6 +152,7 @@ function clickToLoad() { /** * Prepares frame url to replace on button click + * * @param {string} originUrl passed origin frame url * @param {string} unblockTokenName param name for further validation * @param {string} unblockTokenValue param value for further validation @@ -215,6 +218,7 @@ function clickToLoad() { /** * Checks whether the rule has 'frame' or 'subdocument' modifier + * * @param {string} rule blocking rules passed into redirect * @returns {boolean} */ @@ -231,6 +235,7 @@ function clickToLoad() { }; /** * Checks whether script runs inside a frame + * * @returns {boolean} */ const isInsideFrame = () => window.self !== window.top; diff --git a/src/redirects/google-analytics.js b/src/redirects/google-analytics.js index e448a6b2..654dc91a 100644 --- a/src/redirects/google-analytics.js +++ b/src/redirects/google-analytics.js @@ -78,6 +78,7 @@ export function GoogleAnalytics(source) { /** * checks data object and delays callback + * * @param {object|Array} dataObj gtag payload * @param {string} funcName callback prop name */ diff --git a/src/redirects/index.js b/src/redirects/index.js index a8675278..1b0cb1e2 100644 --- a/src/redirects/index.js +++ b/src/redirects/index.js @@ -22,6 +22,7 @@ import { redirectsMap } from '../../tmp/redirects-map'; /** * Finds redirect resource by it's name + * * @param {string} name - redirect name */ const getRedirectByName = (name) => { @@ -40,6 +41,7 @@ const getRedirectByName = (name) => { /** * Returns redirect code by param + * * @param {Source} source * @returns {string} redirect code */ diff --git a/src/redirects/metrika-yandex-tag.js b/src/redirects/metrika-yandex-tag.js index c42d7f52..32bc7e13 100644 --- a/src/redirects/metrika-yandex-tag.js +++ b/src/redirects/metrika-yandex-tag.js @@ -39,6 +39,7 @@ export function metrikaYandexTag(source) { /** * https://yandex.ru/support/metrica/objects/get-client-id.html + * * @param {string} id * @param {Function} cb */ @@ -66,6 +67,7 @@ export function metrikaYandexTag(source) { /** * https://yandex.ru/support/metrica/objects/reachgoal.html + * * @param {string} id * @param {string} target * @param {object} params diff --git a/src/redirects/metrika-yandex-watch.js b/src/redirects/metrika-yandex-watch.js index 31070c70..48e8ac48 100644 --- a/src/redirects/metrika-yandex-watch.js +++ b/src/redirects/metrika-yandex-watch.js @@ -17,6 +17,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 */ const asyncCallbackFromOptions = (options = {}) => { diff --git a/src/redirects/redirects.js b/src/redirects/redirects.js index 98876584..6ee43cbb 100644 --- a/src/redirects/redirects.js +++ b/src/redirects/redirects.js @@ -9,6 +9,7 @@ import jsYaml from 'js-yaml'; * contentType: image/gif;base64 * content: R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw== * } + * * @typedef {object} Redirect * @property {string} title * @property {string} comment @@ -21,6 +22,7 @@ import jsYaml from 'js-yaml'; class Redirects { /** * Converts rawYaml into JS object with sources titles used as keys + * * @param {string} rawYaml * @returns {Object} - return object with titles in the keys and RedirectSources * in the values @@ -43,6 +45,7 @@ class Redirects { /** * Returns redirect source object + * * @param {string} title * @returns {Redirect} */ diff --git a/src/scriptlets/index.js b/src/scriptlets/index.js index aecc2834..3b5ec0da 100644 --- a/src/scriptlets/index.js +++ b/src/scriptlets/index.js @@ -27,6 +27,7 @@ import { getScriptletFunction } from '../../tmp/scriptlets-func'; /** * Returns scriptlet code by param + * * @param {Source} source * @returns {string|null} scriptlet code * @throws on unknown scriptlet name diff --git a/src/scriptlets/json-prune.js b/src/scriptlets/json-prune.js index 8936c343..1919728f 100644 --- a/src/scriptlets/json-prune.js +++ b/src/scriptlets/json-prune.js @@ -156,6 +156,7 @@ export function jsonPrune(source, propsToRemove, requiredInitialProps, stack) { /** * Prunes properties of 'root' object + * * @param {object} root */ const jsonPruner = (root) => { diff --git a/src/scriptlets/trusted-replace-fetch-response.js b/src/scriptlets/trusted-replace-fetch-response.js index 27b8039d..e091c937 100644 --- a/src/scriptlets/trusted-replace-fetch-response.js +++ b/src/scriptlets/trusted-replace-fetch-response.js @@ -117,6 +117,7 @@ export function trustedReplaceFetchResponse(source, pattern = '', replacement = /** * Create new Response object using original response' properties * and given text as body content + * * @param {Response} response original response to copy properties from * @param {string} textContent text to set as body content * @returns {Response} diff --git a/tests/helpers.js b/tests/helpers.js index bfda7624..b891e0c0 100644 --- a/tests/helpers.js +++ b/tests/helpers.js @@ -16,6 +16,7 @@ export const clearGlobalProps = (...props) => { /** * Returns random number from range inclusively min and max + * * @param {number} min minimum range limit * @param {number} max maximum range limit * @returns {number} @@ -31,6 +32,7 @@ const evalWrapper = eval; /** * Runs scriptlet with given args + * * @param {string} name scriptlet name * @param {Array|undefined} args array of scriptlet args * @param {boolean} [verbose=true] @@ -47,6 +49,7 @@ export const runScriptlet = (name, args, verbose = true) => { /** * Runs redirect + * * @param {string} name redirect name * @param {boolean} [verbose=true] */ @@ -61,6 +64,7 @@ export const runRedirect = (name, verbose = true) => { /** * Clear cookie by name + * * @param {string} cName */ export const clearCookie = (cName) => { diff --git a/tests/index.js b/tests/index.js index bf7e090a..23c3a94f 100644 --- a/tests/index.js +++ b/tests/index.js @@ -16,6 +16,7 @@ const TEST_FILE_NAME_MARKER = '.html'; const testServer = server.init(); /** * Returns false if test failed and true if test passed + * * @param {string} indexFile * @returns {Promise} */