Merge pull request #3708 from aloisklink/style/use-eslint-plugin-tsdoc

Use `eslint-plugin-tsdoc` for TypeScript files instead of `eslint-plugin-jsdoc`

.eslintrc.json

@@ -16,7 +16,6 @@
   "extends": [
     "eslint:recommended",
     "plugin:@typescript-eslint/recommended",
-    "plugin:jsdoc/recommended",
     "plugin:json/recommended",
     "plugin:markdown/recommended",
     "plugin:@cspell/recommended",
@@ -28,16 +27,6 @@
     "no-console": "error",
     "no-prototype-builtins": "off",
     "no-unused-vars": "off",
-    "jsdoc/check-indentation": "off",
-    "jsdoc/check-alignment": "off",
-    "jsdoc/check-line-alignment": "off",
-    "jsdoc/multiline-blocks": "off",
-    "jsdoc/newline-after-description": "off",
-    "jsdoc/tag-lines": "off",
-    "jsdoc/require-param-description": "off",
-    "jsdoc/require-param-type": "off",
-    "jsdoc/require-returns": "off",
-    "jsdoc/require-returns-description": "off",
     "cypress/no-async-tests": "off",
     "@typescript-eslint/ban-ts-comment": [
       "error",
@@ -73,6 +62,29 @@
         "no-console": "off"
       }
     },
+    {
+      "files": ["*.{js,jsx,mjs,cjs}"],
+      "extends": ["plugin:jsdoc/recommended"],
+      "rules": {
+        "jsdoc/check-indentation": "off",
+        "jsdoc/check-alignment": "off",
+        "jsdoc/check-line-alignment": "off",
+        "jsdoc/multiline-blocks": "off",
+        "jsdoc/newline-after-description": "off",
+        "jsdoc/tag-lines": "off",
+        "jsdoc/require-param-description": "off",
+        "jsdoc/require-param-type": "off",
+        "jsdoc/require-returns": "off",
+        "jsdoc/require-returns-description": "off"
+      }
+    },
+    {
+      "files": ["*.{ts,tsx}"],
+      "plugins": ["tsdoc"],
+      "rules": {
+        "tsdoc/syntax": "error"
+      }
+    },
     {
       "files": ["*.spec.{ts,js}", "cypress/**", "demos/**", "**/docs/**"],
       "rules": {

package.json

@@ -120,6 +120,7 @@
     "eslint-plugin-json": "3.1.0",
     "eslint-plugin-markdown": "3.0.0",
     "eslint-plugin-no-only-tests": "^3.0.0",
+    "eslint-plugin-tsdoc": "^0.2.17",
     "express": "4.18.2",
     "globby": "13.1.2",
     "husky": "8.0.1",

packages/mermaid-example-diagram/src/detector.ts

@@ -4,7 +4,7 @@ export const id = 'example-diagram';
 /**
  * Detector function that will be called by mermaid to determine if the diagram is this type of diagram.
  *
- * @param txt The diagram text will be passed to the detector
+ * @param txt - The diagram text will be passed to the detector
  * @returns True if the diagram text matches a diagram of this type
  */
 

packages/mermaid-example-diagram/src/mermaidUtils.ts

@@ -35,18 +35,19 @@ export let setupGraphViewbox: (
 
 /**
  * Function called by mermaid that injects utility functions that help the diagram to be a good citizen.
- * @param _log
- * @param _setLogLevel
- * @param _getConfig
- * @param _sanitizeText
- * @param _setupGraphViewbox
+ *
+ * @param _log - log from mermaid/src/diagramAPI.ts
+ * @param _setLogLevel - setLogLevel from mermaid/src/diagramAPI.ts
+ * @param _getConfig - getConfig from mermaid/src/diagramAPI.ts
+ * @param _sanitizeText - sanitizeText from mermaid/src/diagramAPI.ts
+ * @param _setupGraphViewbox - setupGraphViewbox from mermaid/src/diagramAPI.ts
  */
 export const injectUtils = (
   _log: Record<keyof typeof LEVELS, typeof console.log>,
-  _setLogLevel: any,
-  _getConfig: any,
-  _sanitizeText: any,
-  _setupGraphViewbox: any
+  _setLogLevel: typeof setLogLevel,
+  _getConfig: typeof getConfig,
+  _sanitizeText: typeof sanitizeText,
+  _setupGraphViewbox: typeof setupGraphViewbox
 ) => {
   _log.debug('Mermaid utils injected into example-diagram');
   log.trace = _log.trace;

packages/mermaid/src/__mocks__/mermaidAPI.ts

@@ -11,10 +11,7 @@ import Diagram, { type ParseErrorFunction } from '../Diagram';
 // Normally, we could just do the following to get the original `parse()`
 // implementation, however, requireActual returns a promise and it's not documented how to use withing mock file.
 
-/**
- * @param text
- * @param parseError
- */
+/** {@inheritDoc mermaidAPI.parse} */
 function parse(text: string, parseError?: ParseErrorFunction): boolean {
   addDiagrams();
   const diagram = new Diagram(text, parseError);

packages/mermaid/src/config.ts

@@ -56,7 +56,7 @@ export const updateCurrentConfig = (siteCfg: MermaidConfig, _directives: any[])
  * function _Default value: At default, will mirror Global Config_
  *
  * @param conf - The base currentConfig to use as siteConfig
- * @returns {object} - The siteConfig
+ * @returns The new siteConfig
  */
 export const setSiteConfig = (conf: MermaidConfig): MermaidConfig => {
   siteConfig = assignWithDepth({}, defaultConfig);
@@ -91,7 +91,7 @@ export const updateSiteConfig = (conf: MermaidConfig): MermaidConfig => {
  *
  * **Notes**: Returns **any** values in siteConfig.
  *
- * @returns {object} - The siteConfig
+ * @returns The siteConfig
  */
 export const getSiteConfig = (): MermaidConfig => {
   return assignWithDepth({}, siteConfig);
@@ -107,8 +107,8 @@ export const getSiteConfig = (): MermaidConfig => {
  * keys. Any values found in conf with key found in siteConfig.secure will be replaced with the
  * corresponding siteConfig value.
  *
- * @param {any} conf - The potential currentConfig
- * @returns {any} - The currentConfig merged with the sanitized conf
+ * @param conf - The potential currentConfig
+ * @returns The currentConfig merged with the sanitized conf
  */
 export const setConfig = (conf: MermaidConfig): MermaidConfig => {
   // sanitize(conf);
@@ -131,7 +131,7 @@ export const setConfig = (conf: MermaidConfig): MermaidConfig => {
  *
  * **Notes**: Returns **any** the currentConfig
  *
- * @returns {any} - The currentConfig
+ * @returns The currentConfig
  */
 export const getConfig = (): MermaidConfig => {
   return assignWithDepth({}, currentConfig);
@@ -146,7 +146,7 @@ export const getConfig = (): MermaidConfig => {
  * Ensures options parameter does not attempt to override siteConfig secure keys **Notes**: modifies
  * options in-place
  *
- * @param {any} options - The potential setConfig parameter
+ * @param options - The potential setConfig parameter
  */
 export const sanitize = (options: any) => {
   // Checking that options are not in the list of excluded options
@@ -186,7 +186,7 @@ export const sanitize = (options: any) => {
 /**
  * Pushes in a directive to the configuration
  *
- * @param {object} directive The directive to push in
+ * @param directive - The directive to push in
  */
 export const addDirective = (directive: any) => {
   if (directive.fontFamily) {
@@ -217,7 +217,8 @@ export const addDirective = (directive: any) => {
  *
  * **Notes**: (default: current siteConfig ) (optional, default `getSiteConfig()`)
  *
- * @param config
+ * @param config - base set of values, which currentConfig could be **reset** to.
+ * Defaults to the current siteConfig (e.g returned by {@link getSiteConfig}).
  */
 export const reset = (config = siteConfig): void => {
   // Replace current config with siteConfig

packages/mermaid/src/defaultConfig.ts

@@ -8,19 +8,27 @@ import { MermaidConfig } from './config.type';
  *
  * These are the default options which can be overridden with the initialization call like so:
  *
- * **Example 1:**<pre> mermaid.initialize({ flowchart:{ htmlLabels: false } }); </pre>
+ * **Example 1:**
  *
- * **Example 2:**<pre> <script> var config = { startOnLoad:true, flowchart:{ useMaxWidth:true,
- * htmlLabels:true, curve:'cardinal', },
+ * ```js
+ * mermaid.initialize({ flowchart:{ htmlLabels: false } });
+ * ```
  *
- *     securityLevel:'loose',
+ * **Example 2:**
  *
- * }; mermaid.initialize(config); </script> </pre>
+ * ```html
+ * <script>
+ * var config = {
+ *   startOnLoad:true,
+ *   flowchart:{ useMaxWidth:true, htmlLabels:true, curve:'cardinal'},
+ *   securityLevel:'loose',
+ * };
+ * mermaid.initialize(config);
+ * </script>
+ * ```
  *
  * A summary of all options and their defaults is found [here](#mermaidapi-configuration-defaults).
  * A description of each option follows below.
- *
- * @name Configuration
  */
 const config: Partial<MermaidConfig> = {
   /**
@@ -30,8 +38,16 @@ const config: Partial<MermaidConfig> = {
    * | --------- | --------------- | ------ | -------- | ---------------------------------------------- |
    * | theme     | Built in Themes | string | Optional | 'default', 'forest', 'dark', 'neutral', 'null' |
    *
-   * **Notes:** To disable any pre-defined mermaid theme, use "null".<pre> "theme": "forest",
-   * "themeCSS": ".node rect { fill: red; }" </pre>
+   * **Notes:** To disable any pre-defined mermaid theme, use "null".
+   *
+   * @example
+   *
+   * ```js
+   * {
+   *   "theme": "forest",
+   *   "themeCSS": ".node rect { fill: red; }"
+   * }
+   * ```
    */
   theme: 'default',
   themeVariables: theme['default'].getThemeVariables(),

packages/mermaid/src/diagram-api/detectType.ts

@@ -9,10 +9,13 @@ const anyComment = /\s*%%.*\n/gm;
 const detectors: Record<string, DetectorRecord> = {};
 
 /**
- * @function detectType Detects the type of the graph text. Takes into consideration the possible
- *   existence of an %%init directive
+ * Detects the type of the graph text.
  *
- *   ```mermaid
+ * Takes into consideration the possible existence of an `%%init` directive
+ *
+ * @param text - The text defining the graph. For example:
+ *
+ * ```mermaid
  *   %%{initialize: {"startOnLoad": true, logLevel: "fatal" }}%%
  *   graph LR
  *    a-->b
@@ -23,13 +26,9 @@ const detectors: Record<string, DetectorRecord> = {};
  *    f-->g
  *    g-->h
  * ```
- * @param {string} text The text defining the graph
- * @param {{
- *   class: { defaultRenderer: string } | undefined;
- *   state: { defaultRenderer: string } | undefined;
- *   flowchart: { defaultRenderer: string } | undefined;
- * }} [config]
- * @returns {string} A graph definition key
+ *
+ * @param config - The mermaid config.
+ * @returns A graph definition key
  */
 export const detectType = function (text: string, config?: MermaidConfig): string {
   text = text.replace(directive, '').replace(anyComment, '\n');

packages/mermaid/src/diagrams/common/common.ts

@@ -4,8 +4,8 @@ import { MermaidConfig } from '../../config.type';
 /**
  * Gets the rows of lines in a string
  *
- * @param {string | undefined} s The string to check the lines for
- * @returns {string[]} The rows in that string
+ * @param s - The string to check the lines for
+ * @returns The rows in that string
  */
 export const getRows = (s?: string): string[] => {
   if (!s) {
@@ -18,8 +18,8 @@ export const getRows = (s?: string): string[] => {
 /**
  * Removes script tags from a text
  *
- * @param {string} txt The text to sanitize
- * @returns {string} The safer text
+ * @param txt - The text to sanitize
+ * @returns The safer text
  */
 export const removeScript = (txt: string): string => {
   return DOMPurify.sanitize(txt);
@@ -68,8 +68,8 @@ export const lineBreakRegex = /<br\s*\/?>/gi;
 /**
  * Whether or not a text has any line breaks
  *
- * @param {string} text The text to test
- * @returns {boolean} Whether or not the text has breaks
+ * @param text - The text to test
+ * @returns Whether or not the text has breaks
  */
 export const hasBreaks = (text: string): boolean => {
   return lineBreakRegex.test(text);
@@ -78,8 +78,8 @@ export const hasBreaks = (text: string): boolean => {
 /**
  * Splits on <br> tags
  *
- * @param {string} text Text to split
- * @returns {string[]} List of lines as strings
+ * @param text - Text to split
+ * @returns List of lines as strings
  */
 export const splitBreaks = (text: string): string[] => {
   return text.split(lineBreakRegex);
@@ -88,8 +88,8 @@ export const splitBreaks = (text: string): string[] => {
 /**
  * Converts placeholders to line breaks in HTML
  *
- * @param {string} s HTML with placeholders
- * @returns {string} HTML with breaks instead of placeholders
+ * @param s - HTML with placeholders
+ * @returns HTML with breaks instead of placeholders
  */
 const placeholderToBreak = (s: string): string => {
   return s.replace(/#br#/g, '<br/>');
@@ -98,8 +98,8 @@ const placeholderToBreak = (s: string): string => {
 /**
  * Opposite of `placeholderToBreak`, converts breaks to placeholders
  *
- * @param {string} s HTML string
- * @returns {string} String with placeholders
+ * @param s - HTML string
+ * @returns String with placeholders
  */
 const breakToPlaceholder = (s: string): string => {
   return s.replace(lineBreakRegex, '#br#');
@@ -108,8 +108,8 @@ const breakToPlaceholder = (s: string): string => {
 /**
  * Gets the current URL
  *
- * @param {boolean} useAbsolute Whether to return the absolute URL or not
- * @returns {string} The current URL
+ * @param useAbsolute - Whether to return the absolute URL or not
+ * @returns The current URL
  */
 const getUrl = (useAbsolute: boolean): string => {
   let url = '';
@@ -130,21 +130,24 @@ const getUrl = (useAbsolute: boolean): string => {
 /**
  * Converts a string/boolean into a boolean
  *
- * @param {string | boolean} val String or boolean to convert
- * @returns {boolean} The result from the input
+ * @param val - String or boolean to convert
+ * @returns The result from the input
  */
 export const evaluate = (val?: string | boolean): boolean =>
   val === false || ['false', 'null', '0'].includes(String(val).trim().toLowerCase()) ? false : true;
 
 /**
  * Makes generics in typescript syntax
  *
- * @example <caption>Array of array of strings in typescript syntax</caption>
- *   // returns "Array<Array<string>>"
- *   parseGenericTypes('Array~Array~string~~');
+ * @example
+ * Array of array of strings in typescript syntax
  *
- * @param {string} text The text to convert
- * @returns {string} The converted string
+ * ```js
+ * // returns "Array<Array<string>>"
+ * parseGenericTypes('Array~Array~string~~');
+ * ```
+ * @param text - The text to convert
+ * @returns The converted string
  */
 export const parseGenericTypes = function (text: string): string {
   let cleanedText = text;