fix docs

Squashed commit of the following: commit 3c5416b Author: Slava Leleka <v.leleka@adguard.com> Date: Mon Apr 15 16:59:53 2024 +0400 fix trusted-dispatch-event docs style commit ce7e9e7 Merge: 8e756b7 b9e38c0 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon Apr 15 16:49:32 2024 +0400 Merge branch 'master' into fix/docs-002 commit 8e756b7 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon Apr 15 16:18:04 2024 +0400 fix docs commit 520cdb2 Author: Slava Leleka <v.leleka@adguard.com> Date: Mon Apr 15 16:16:13 2024 +0400 throw an error if wiki pages cannot be created commit bcb3d55 Author: Slava Leleka <v.leleka@adguard.com> Date: Fri Apr 12 20:18:52 2024 +0400 test no added jsdoc tag commit 39eddf9 Author: Slava Leleka <v.leleka@adguard.com> Date: Fri Apr 12 20:12:59 2024 +0400 fix docs for v1.10.25
AdguardTeam · Apr 15, 2024 · 2e1dcee · 2e1dcee
1 parent b9e38c0
commit 2e1dcee
Show file tree

Hide file tree

Showing 25 changed files with 818 additions and 47 deletions.
diff --git a/scripts/build-docs.js b/scripts/build-docs.js
@@ -49,7 +49,8 @@ const aboutTrustedScriptletsPath = path.resolve(
 /**
  * Collects required comments from files
  *
- * @returns {object} describing object for scriptlets and redirects
+ * @returns {object} describing object for scriptlets, trustedScriptlets, and redirects
+ * @throws {Error} If {@link getDataFromFiles} throws an error.
  */
 const manageDataFromFiles = () => {
     const dataFromScriptletsFiles = getDataFromFiles(
@@ -130,6 +131,7 @@ ${description}${EOL}
  * Generates markdown list and describing text for static redirect resources
  *
  * @returns {MarkdownData}
+ * @throws {Error} If some crucial data is missing.
  */
 const getMarkdownDataForStaticRedirects = () => {
     const staticRedirects = fs.readFileSync(path.resolve(__dirname, staticRedirectsPath), { encoding: 'utf8' });
@@ -168,6 +170,7 @@ ${description}${EOL}
  * Generates markdown list and describing text for blocking redirect resources, i.e click2load.html
  *
  * @returns {MarkdownData}
+ * @throws {Error} If some crucial data is missing.
  */
 const getMarkdownDataForBlockingRedirects = () => {
     const BLOCKING_REDIRECTS_SOURCE_SUB_DIR = 'blocking-redirects';
@@ -208,6 +211,8 @@ ${description}${EOL}
 
 /**
  * Builds about wiki pages for scriptlets and redirects
+ *
+ * @throws {Error} If wiki pages cannot be created. The reason is logged before throwing.
  */
 const buildWikiAboutPages = () => {
     try {
@@ -228,7 +233,6 @@ ${scriptletsMarkdownData.body}`;
             scriptletsPageContent,
         );
 
-        // eslint-disable-next-line max-len
         const trustedScriptletsPageContent = `# <a id="trusted-scriptlets"></a> Available Trusted Scriptlets${EOL}
 ${trustedScriptletsMarkdownData.list}${EOL}* * *${EOL}
 ${trustedScriptletsMarkdownData.body}`;
@@ -237,18 +241,17 @@ ${trustedScriptletsMarkdownData.body}`;
             trustedScriptletsPageContent,
         );
 
-        /* eslint-disable max-len */
         const redirectsPageContent = `# <a id="redirect-resources"></a> Available Redirect resources${EOL}
 ${staticRedirectsMarkdownData.list}${redirectsMarkdownData.list}${blockingRedirectsMarkdownData.list}${EOL}* * *${EOL}
 ${staticRedirectsMarkdownData.body}${redirectsMarkdownData.body}${blockingRedirectsMarkdownData.body}`;
-        /* eslint-enable max-len */
         fs.writeFileSync(
             path.resolve(__dirname, aboutRedirectsPath),
             redirectsPageContent,
         );
     } catch (e) {
         // eslint-disable-next-line no-console
         console.log(e.message);
+        throw new Error('Cannot create wiki pages.');
     }
 };
 

diff --git a/scripts/helpers.js b/scripts/helpers.js
@@ -44,7 +44,9 @@ const getFilesList = (relativeDirPath) => {
  * In one file might be comments describing scriptlet and redirect as well.
  *
  * @param {string} filePath absolute path to file
+ *
  * @returns {CommentTag[]}
+ * @throws {Error} If there is no description comment found in file, or more than one such comment found.
  */
 const getDescribingCommentTags = (filePath) => {
     const fileContent = fs.readFileSync(filePath, { encoding: 'utf8' });
@@ -92,7 +94,9 @@ Please add one OR edit the list of NON_SCRIPTLETS_FILES / NON_REDIRECTS_FILES.`)
  *
  * @param {CommentTag[]} commentTags parsed tags from describing comment
  * @param {string} source relative path to file
- * @returns {DescribingCommentData}
+ *
+ * @returns {DescribingCommentData} JSDoc comment data.
+ * @throws {Error} If `@added` tag is missing
  */
 const prepareCommentsData = (commentTags, source) => {
     const [typeTag, descriptionTag, addedTag] = commentTags;
@@ -115,7 +119,9 @@ const prepareCommentsData = (commentTags, source) => {
  *
  * @param {string[]} filesList list of files in directory
  * @param {string} relativeDirPath relative path to directory
+ *
  * @returns {DescribingCommentData}
+ * @throws {Error} if {@link getDescribingCommentTags} or {@link prepareCommentsData} throws an error.
  */
 const getDataFromFiles = (filesList, relativeDirPath) => {
     const pathToDir = path.resolve(__dirname, relativeDirPath);

diff --git a/src/scriptlets/fingerprintjs2.ts b/src/scriptlets/fingerprintjs2.ts
@@ -13,6 +13,6 @@ import { Fingerprintjs2 } from '../redirects/fingerprintjs2';
  * example.org#%#//scriptlet('fingerprintjs2')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Fingerprintjs2 };
diff --git a/src/scriptlets/fingerprintjs3.ts b/src/scriptlets/fingerprintjs3.ts
@@ -13,6 +13,6 @@ import { Fingerprintjs3 } from '../redirects/fingerprintjs3';
  * example.org#%#//scriptlet('fingerprintjs3')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Fingerprintjs3 };
diff --git a/src/scriptlets/gemius.ts b/src/scriptlets/gemius.ts
@@ -13,6 +13,6 @@ import { Gemius } from '../redirects/gemius';
  * example.org#%#//scriptlet('gemius')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Gemius };
diff --git a/src/scriptlets/google-analytics-ga.ts b/src/scriptlets/google-analytics-ga.ts
@@ -12,6 +12,6 @@ import { GoogleAnalyticsGa } from '../redirects/google-analytics-ga';
  * example.org#%#//scriptlet('google-analytics-ga')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { GoogleAnalyticsGa };
diff --git a/src/scriptlets/google-analytics.ts b/src/scriptlets/google-analytics.ts
@@ -12,6 +12,6 @@ import { GoogleAnalytics } from '../redirects/google-analytics';
  * example.org#%#//scriptlet('google-analytics')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { GoogleAnalytics };
diff --git a/src/scriptlets/google-ima3.ts b/src/scriptlets/google-ima3.ts
@@ -12,6 +12,6 @@ import { GoogleIma3 } from '../redirects/google-ima3';
  * example.org#%#//scriptlet('google-ima3')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { GoogleIma3 };
diff --git a/src/scriptlets/googlesyndication-adsbygoogle.ts b/src/scriptlets/googlesyndication-adsbygoogle.ts
@@ -12,6 +12,6 @@ import { GoogleSyndicationAdsByGoogle } from '../redirects/googlesyndication-ads
  * example.org#%#//scriptlet('googlesyndication-adsbygoogle')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { GoogleSyndicationAdsByGoogle };
diff --git a/src/scriptlets/googletagservices-gpt.ts b/src/scriptlets/googletagservices-gpt.ts
@@ -12,6 +12,6 @@ import { GoogleTagServicesGpt } from '../redirects/googletagservices-gpt';
  * example.org#%#//scriptlet('googletagservices-gpt')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { GoogleTagServicesGpt };
diff --git a/src/scriptlets/href-sanitizer.ts b/src/scriptlets/href-sanitizer.ts
@@ -88,7 +88,7 @@ import {
  *     </div>
  *     ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 
 export function hrefSanitizer(

diff --git a/src/scriptlets/json-prune-fetch-response.ts b/src/scriptlets/json-prune-fetch-response.ts
@@ -113,7 +113,7 @@ import {
  *     example.org#%#//scriptlet('json-prune-fetch-response')
  *     ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export function jsonPruneFetchResponse(
     source: Source,

diff --git a/src/scriptlets/json-prune-xhr-response.ts b/src/scriptlets/json-prune-xhr-response.ts
@@ -110,7 +110,7 @@ import {
  *     example.org#%#//scriptlet('json-prune-xhr-response')
  *     ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 
 interface CustomXMLHttpRequest extends XMLHttpRequest {

diff --git a/src/scriptlets/matomo.ts b/src/scriptlets/matomo.ts
@@ -12,6 +12,6 @@ import { Matomo } from '../redirects/matomo';
  * example.org#%#//scriptlet('matomo')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Matomo };
diff --git a/src/scriptlets/metrika-yandex-tag.ts b/src/scriptlets/metrika-yandex-tag.ts
@@ -13,6 +13,6 @@ import { metrikaYandexTag } from '../redirects/metrika-yandex-tag';
  * example.org#%#//scriptlet('metrika-yandex-tag')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { metrikaYandexTag };
diff --git a/src/scriptlets/metrika-yandex-watch.ts b/src/scriptlets/metrika-yandex-watch.ts
@@ -13,6 +13,6 @@ import { metrikaYandexWatch } from '../redirects/metrika-yandex-watch';
  * example.org#%#//scriptlet('metrika-yandex-watch')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { metrikaYandexWatch };
diff --git a/src/scriptlets/naver-wcslog.ts b/src/scriptlets/naver-wcslog.ts
@@ -12,6 +12,6 @@ import { NaverWcslog } from '../redirects/naver-wcslog';
  * example.org#%#//scriptlet('naver-wcslog')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { NaverWcslog };
diff --git a/src/scriptlets/no-protected-audience.ts b/src/scriptlets/no-protected-audience.ts
@@ -19,7 +19,7 @@ import {
  * example.org#%#//scriptlet('no-protected-audience')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export function noProtectedAudience(source: Source) {
     // Prevent XMLDocuments from being tampered with generic scriptlet rule

diff --git a/src/scriptlets/pardot-1.0.ts b/src/scriptlets/pardot-1.0.ts
@@ -14,6 +14,6 @@ import { Pardot } from '../redirects/pardot-1.0';
  * example.org#%#//scriptlet('pardot-1.0')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Pardot };
diff --git a/src/scriptlets/prebid.ts b/src/scriptlets/prebid.ts
@@ -13,6 +13,6 @@ import { Prebid } from '../redirects/prebid';
  * example.org#%#//scriptlet('prebid')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { Prebid };
diff --git a/src/scriptlets/scorecardresearch-beacon.ts b/src/scriptlets/scorecardresearch-beacon.ts
@@ -11,6 +11,6 @@ import { ScoreCardResearchBeacon } from '../redirects/scorecardresearch-beacon';
  * example.org#%#//scriptlet('scorecardresearch-beacon')
  * ```
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 export { ScoreCardResearchBeacon };
diff --git a/src/scriptlets/trusted-dispatch-event.ts b/src/scriptlets/trusted-dispatch-event.ts
@@ -9,15 +9,16 @@ import {
  * Dispatches a custom event on a specified target.
  *
  * ### Syntax
+ *
  * ```text
  * example.org#%#//scriptlet('trusted-dispatch-event', event[, target])
  * ```
  *
  * - `event` — required, name of the event to dispatch
  * - `target` — optional, target on which event will be invoked. Possible values:
- *   - CSS selector — dispatch event on the element with the specified selector
- *   - `window` — dispatch event on the window object
- *   - if not set, then "document" is used — it's default value
+ *     - CSS selector — dispatch event on the element with the specified selector
+ *     - `window` — dispatch event on the window object
+ *     - if not set, then "document" is used — it's default value
  *
  * ### Examples
  *

diff --git a/src/scriptlets/trusted-suppress-native-method.ts b/src/scriptlets/trusted-suppress-native-method.ts
@@ -98,7 +98,7 @@ import {
  *
  *     <!-- markdownlint-enable line-length -->
  *
- * v1.10.25.
+ * @added v1.10.25.
  */
 /* eslint-enable max-len */
 export function trustedSuppressNativeMethod(