style: fix eslint-plugin-tsdoc linting issues

Mostly, fixing these eslint-plugin-tsdoc style issues involved: - Moving types from JSDoc to TypeScript types - Making sure that all `@param paramName - description` had both a `-` and a description. Occasionally, for some functions, if the JSDoc was completely empty, I just deleted it, since there was no point in keeping it.
2025-09-16 13:59:54 +02:00 · 2022-10-22 13:30:50 +01:00
parent e6f19ff461
commit 7e5689d0b9
15 changed files with 303 additions and 250 deletions
--- a/packages/mermaid/src/utils.ts
+++ b/packages/mermaid/src/utils.ts
@@ -4,6 +4,7 @@ import {
  curveBasis,
  curveBasisClosed,
  curveBasisOpen,
+  CurveFactory,
  curveLinear,
  curveLinearClosed,
  curveMonotoneX,
@@ -42,13 +43,13 @@ const directiveWithoutOpen =
  /\s*(?:(?:(\w+)(?=:):|(\w+))\s*(?:(?:(\w+))|((?:(?![}][%]{2}).|\r?\n)*))?\s*)(?:[}][%]{2})?/gi;

 /**
- * @function detectInit Detects the init config object from the text
- * @param config
+ * Detects the init config object from the text
 *
- *   ```mermaid
+ * @param text - The text defining the graph. For example:
 *
- *   %%{init: {"theme": "debug", "logLevel": 1 }}%%
- *   graph LR
+ * ```mermaid
+ * %%{init: {"theme": "debug", "logLevel": 1 }}%%
+ * graph LR
 *      a-->b
 *      b-->c
 *      c-->d
@@ -58,11 +59,11 @@ const directiveWithoutOpen =
 *      g-->h
 * ```
 *
- *   Or
+ * Or
 *
- *   ```mermaid
- *   %%{initialize: {"theme": "dark", logLevel: "debug" }}%%
- *   graph LR
+ * ```mermaid
+ * %%{initialize: {"theme": "dark", logLevel: "debug" }}%%
+ * graph LR
 *    a-->b
 *    b-->c
 *    c-->d
@@ -71,8 +72,9 @@ const directiveWithoutOpen =
 *    f-->g
 *    g-->h
 * ```
- * @param {string} text The text defining the graph
- * @returns {object} The json object representing the init passed to mermaid.initialize()
+ *
+ * @param config - Optional mermaid configuration object.
+ * @returns The json object representing the init passed to mermaid.initialize()
 */
 export const detectInit = function (text: string, config?: MermaidConfig): MermaidConfig {
  const inits = detectDirective(text, /(?:init\b)|(?:initialize\b)/);
@@ -104,12 +106,14 @@ export const detectInit = function (text: string, config?: MermaidConfig): Merma
 };

 /**
- * @function detectDirective Detects the directive from the text. Text can be single line or
- *   multiline. If type is null or omitted the first directive encountered in text will be returned
+ * Detects the directive from the text.
 *
- *   ```mermaid
- *   graph LR
- *    %%{someDirective}%%
+ * Text can be single line or multiline. If type is null or omitted,
+ * the first directive encountered in text will be returned
+ *
+ * ```mermaid
+ * graph LR
+ * %%{someDirective}%%
 *    a-->b
 *    b-->c
 *    c-->d
@@ -118,13 +122,16 @@ export const detectInit = function (text: string, config?: MermaidConfig): Merma
 *    f-->g
 *    g-->h
 * ```
- * @param {string} text The text defining the graph
- * @param {string | RegExp} type The directive to return (default: null)
- * @returns {object | Array} An object or Array representing the directive(s): { type: string, args:
- *   object|null } matched by the input type if a single directive was found, that directive object
- *   will be returned.
+ *
+ * @param text - The text defining the graph
+ * @param type - The directive to return (default: `null`)
+ * @returns An object or Array representing the directive(s) matched by the input type.
+ * If a single directive was found, that directive object will be returned.
 */
-export const detectDirective = function (text, type = null) {
+export const detectDirective = function (
+  text: string,
+  type: string | RegExp = null
+): { type?: string; args?: any } | { type?: string; args?: any }[] {
  try {
    const commentWithoutDirectives = new RegExp(
      `[%]{2}(?![{]${directiveWithoutOpen.source})(?=[}][%]{2}).*\n`,
@@ -166,12 +173,13 @@ export const detectDirective = function (text, type = null) {
 };

 /**
- * @function isSubstringInArray Detects whether a substring in present in a given array
- * @param {string} str The substring to detect
- * @param {Array} arr The array to search
- * @returns {number} The array index containing the substring or -1 if not present
+ * Detects whether a substring in present in a given array
+ *
+ * @param str - The substring to detect
+ * @param arr - The array to search
+ * @returns The array index containing the substring or -1 if not present
 */
-export const isSubstringInArray = function (str, arr) {
+export const isSubstringInArray = function (str: string, arr: string[]): number {
  for (let i = 0; i < arr.length; i++) {
    if (arr[i].match(str)) {
      return i;
@@ -183,26 +191,26 @@ export const isSubstringInArray = function (str, arr) {
 /**
 * Returns a d3 curve given a curve name
 *
- * @param {string | undefined} interpolate The interpolation name
- * @param {any} defaultCurve The default curve to return
- * @returns {import('d3-shape').CurveFactory} The curve factory to use
+ * @param interpolate - The interpolation name
+ * @param defaultCurve - The default curve to return
+ * @returns The curve factory to use
 */
-export const interpolateToCurve = (interpolate, defaultCurve) => {
+export function interpolateToCurve(interpolate?: string, defaultCurve: CurveFactory): CurveFactory {
  if (!interpolate) {
    return defaultCurve;
  }
  const curveName = `curve${interpolate.charAt(0).toUpperCase() + interpolate.slice(1)}`;
  return d3CurveTypes[curveName] || defaultCurve;
-};
+}

 /**
 * Formats a URL string
 *
- * @param {string} linkStr String of the URL
- * @param {{ securityLevel: string }} config Configuration passed to MermaidJS
- * @returns {string | undefined} The formatted URL
+ * @param linkStr - String of the URL
+ * @param config - Configuration passed to MermaidJS
+ * @returns The formatted URL or `undefined`.
 */
-export const formatUrl = (linkStr, config) => {
+export function formatUrl(linkStr: string, config: { securityLevel: string }): string | undefined {
  const url = linkStr.trim();

  if (url) {
@@ -212,15 +220,15 @@ export const formatUrl = (linkStr, config) => {

    return url;
  }
-};
+}

 /**
 * Runs a function
 *
- * @param {string} functionName A dot separated path to the function relative to the `window`
- * @param {...any} params Parameters to pass to the function
+ * @param functionName - A dot separated path to the function relative to the `window`
+ * @param params - Parameters to pass to the function
 */
-export const runFunc = (functionName, ...params) => {
+export const runFunc = (functionName: string, ...params) => {
  const arrPaths = functionName.split('.');

  const len = arrPaths.length - 1;
@@ -237,28 +245,31 @@ export const runFunc = (functionName, ...params) => {
  obj[fnName](...params);
 };

-/**
- * @typedef {object} Point A (x, y) point
- * @property {number} x The x value
- * @property {number} y The y value
- */
+/** A (x, y) point */
+interface Point {
+  /** The x value */
+  x: number;
+  /** The y value */
+  y: number;
+}

 /**
 * Finds the distance between two points using the Distance Formula
 *
- * @param {Point} p1 The first point
- * @param {Point} p2 The second point
- * @returns {number} The distance
+ * @param p1 - The first point
+ * @param p2 - The second point
+ * @returns The distance between the two points.
 */
-const distance = (p1, p2) =>
-  p1 && p2 ? Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2)) : 0;
+function distance(p1: Point, p2: Point): number {
+  return p1 && p2 ? Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2)) : 0;
+}

 /**
- * @param {Point[]} points List of points
- * @returns {Point}
- * @todo Give this a description
+ * TODO: Give this a description
+ *
+ * @param points - List of points
 */
-const traverseEdge = (points) => {
+function traverseEdge(points: Point[]): Point {
  let prevPoint;
  let totalDistance = 0;

@@ -297,20 +308,17 @@ const traverseEdge = (points) => {
    prevPoint = point;
  });
  return center;
-};
+}

 /**
- * Alias for `traverseEdge`
- *
- * @param {Point[]} points List of points
- * @returns {Point} Return result of `transverseEdge`
+ * {@inheritdoc traverseEdge}
 */
-const calcLabelPosition = (points) => {
+function calcLabelPosition(points: Point[]): Point {
  if (points.length === 1) {
    return points[0];
  }
  return traverseEdge(points);
-};
+}

 const calcCardinalityPosition = (isRelationTypePresent, points, initialPosition) => {
  let prevPoint;
@@ -366,14 +374,18 @@ const calcCardinalityPosition = (isRelationTypePresent, points, initialPosition)
 };

 /**
- * Position ['start_left', 'start_right', 'end_left', 'end_right']
+ * Calculates the terminal label position.
 *
- * @param {any} terminalMarkerSize
- * @param {any} position
- * @param {any} _points
- * @returns {any}
+ * @param terminalMarkerSize - Terminal marker size.
+ * @param position - Position of label relative to points.
+ * @param _points - Array of points.
+ * @returns - The `cardinalityPosition`.
 */
-const calcTerminalLabelPosition = (terminalMarkerSize, position, _points) => {
+function calcTerminalLabelPosition(
+  terminalMarkerSize: number,
+  position: 'start_left' | 'start_right' | 'end_left' | 'end_right',
+  _points: Point[]
+): Point {
  // Todo looking to faster cloning method
  let points = JSON.parse(JSON.stringify(_points));
  let prevPoint;
@@ -441,15 +453,15 @@ const calcTerminalLabelPosition = (terminalMarkerSize, position, _points) => {
    cardinalityPosition.y = -Math.cos(angle) * d + (points[0].y + center.y) / 2 - 5;
  }
  return cardinalityPosition;
-};
+}

 /**
 * Gets styles from an array of declarations
 *
- * @param {string[]} arr Declarations
- * @returns {{ style: string; labelStyle: string }} The styles grouped as strings
+ * @param arr - Declarations
+ * @returns The styles grouped as strings
 */
-export const getStylesFromArray = (arr) => {
+export function getStylesFromArray(arr: string[]): { style: string; labelStyle: string } {
  let style = '';
  let labelStyle = '';

@@ -465,7 +477,7 @@ export const getStylesFromArray = (arr) => {
  }

  return { style: style, labelStyle: labelStyle };
-};
+}

 let cnt = 0;
 export const generateId = () => {
@@ -474,10 +486,12 @@ export const generateId = () => {
 };

 /**
- * @param {any} length
- * @returns {any}
+ * Generates a random hexadecimal id of the given length.
+ *
+ * @param length - Length of ID.
+ * @returns The generated ID.
 */
-function makeid(length) {
+function makeid(length: number): string {
  let result = '';
  const characters = '0123456789abcdef';
  const charactersLength = characters.length;
@@ -510,22 +524,25 @@ export const getTextObj = function () {
 /**
 * Adds text to an element
 *
- * @param {SVGElement} elem Element to add text to
- * @param {{
- *   text: string;
- *   x: number;
- *   y: number;
- *   anchor: 'start' | 'middle' | 'end';
- *   fontFamily: string;
- *   fontSize: string | number;
- *   fontWeight: string | number;
- *   fill: string;
- *   class: string | undefined;
- *   textMargin: number;
- * }} textData
- * @returns {SVGTextElement} Text element with given styling and content
+ * @param elem - SVG Element to add text to
+ * @param textData - Text options.
+ * @returns Text element with given styling and content
 */
-export const drawSimpleText = function (elem, textData) {
+export const drawSimpleText = function (
+  elem: SVGElement,
+  textData: {
+    text: string;
+    x: number;
+    y: number;
+    anchor: 'start' | 'middle' | 'end';
+    fontFamily: string;
+    fontSize: string | number;
+    fontWeight: string | number;
+    fill: string;
+    class: string | undefined;
+    textMargin: number;
+  }
+): SVGTextElement {
  // Remove and ignore br:s
  const nText = textData.text.replace(common.lineBreakRegex, ' ');

@@ -623,43 +640,56 @@ const breakString = memoize(
 *
 * If the wrapped text text has greater height, we extend the height, so it's value won't overflow.
 *
- * @param {any} text The text to measure
- * @param {any} config - The config for fontSize, fontFamily, and fontWeight all impacting the
+ * @param text - The text to measure
+ * @param config - The config for fontSize, fontFamily, and fontWeight all impacting the
 *   resulting size
- * @returns {any} - The height for the given text
+ * @returns The height for the given text
 */
-export const calculateTextHeight = function (text, config) {
+export function calculateTextHeight(
+  text: Parameters<typeof calculateTextDimensions>[0],
+  config: Parameters<typeof calculateTextDimensions>[1]
+): ReturnType<typeof calculateTextDimensions>['height'] {
  config = Object.assign(
    { fontSize: 12, fontWeight: 400, fontFamily: 'Arial', margin: 15 },
    config
  );
  return calculateTextDimensions(text, config).height;
-};
+}

 /**
 * This calculates the width of the given text, font size and family.
 *
- * @param {any} text - The text to calculate the width of
- * @param {any} config - The config for fontSize, fontFamily, and fontWeight all impacting the
+ * @param text - The text to calculate the width of
+ * @param config - The config for fontSize, fontFamily, and fontWeight all impacting the
 *   resulting size
- * @returns {any} - The width for the given text
+ * @returns The width for the given text
 */
-export const calculateTextWidth = function (text, config) {
+export function calculateTextWidth(
+  text: Parameters<typeof calculateTextDimensions>[0],
+  config: Parameters<typeof calculateTextDimensions>[1]
+): ReturnType<typeof calculateTextDimensions>['width'] {
  config = Object.assign({ fontSize: 12, fontWeight: 400, fontFamily: 'Arial' }, config);
  return calculateTextDimensions(text, config).width;
-};
+}

 /**
 * This calculates the dimensions of the given text, font size, font family, font weight, and
 * margins.
 *
- * @param {any} text - The text to calculate the width of
- * @param {any} config - The config for fontSize, fontFamily, fontWeight, and margin all impacting
+ * @param text - The text to calculate the width of
+ * @param config - The config for fontSize, fontFamily, fontWeight, and margin all impacting
 *   the resulting size
- * @returns - The width for the given text
+ * @returns The dimensions for the given text
 */
 export const calculateTextDimensions = memoize(
-  function (text, config) {
+  function (
+    text: string,
+    config: {
+      fontSize?: number;
+      fontWeight?: number;
+      fontFamily?: string;
+    }
+  ) {
    config = Object.assign({ fontSize: 12, fontWeight: 400, fontFamily: 'Arial' }, config);
    const { fontSize, fontFamily, fontWeight } = config;
    if (!text) {
@@ -741,10 +771,10 @@ let decoder;
 /**
 * Decodes HTML, source: {@link https://github.com/shrpne/entity-decode/blob/v2.0.1/browser.js}
 *
- * @param {string} html HTML as a string
- * @returns {string} Unescaped HTML
+ * @param html - HTML as a string
+ * @returns Unescaped HTML
 */
-export const entityDecode = function (html) {
+export const entityDecode = function (html: string): string {
  decoder = decoder || document.createElement('div');
  // Escape HTML before decoding for HTML Entities
  html = escape(html).replace(/%26/g, '&').replace(/%23/g, '#').replace(/%3B/g, ';');
@@ -756,9 +786,9 @@ export const entityDecode = function (html) {
 /**
 * Sanitizes directive objects
 *
- * @param {object} args Directive's JSON
+ * @param args - Directive's JSON
 */
-export const directiveSanitizer = (args) => {
+export const directiveSanitizer = (args: any) => {
  log.debug('directiveSanitizer called with', args);
  if (typeof args === 'object') {
    // check for array
@@ -845,12 +875,12 @@ export interface DetailedError {
  hash: any;
 }

-/** @param error */
+/** @param error - The error to check */
 export function isDetailedError(error: unknown): error is DetailedError {
  return 'str' in error;
 }

-/** @param error */
+/** @param error - The error to convert to an error message */
 export function getErrorMessage(error: unknown): string {
  if (error instanceof Error) {
    return error.message;