refactor(many): fix docs parsing for arrow functions

matyasf · matyasf · commit eed72caac634 · 2025-07-16T14:06:50.000+02:00
The new parsing algorithm was wrong for cases like const f = () =&gt; {}. This patch fixes it
diff --git a/packages/__docs__/buildScripts/build-docs.mts b/packages/__docs__/buildScripts/build-docs.mts
@@ -63,39 +63,32 @@ const pathsToProcess = [
   'CHANGELOG.md',
   '**/packages/**/*.md', // package READMEs
   '**/docs/**/*.md', // general docs
-  '**/src/*.{js,ts,tsx}', // util src files
-  '**/src/*/*.{js,ts,tsx}', // component src files
-  '**/src/*/*/*.{js,ts,tsx}', // child component src files
+  '**/src/*.{ts,tsx}', // util src files
+  '**/src/*/*.{ts,tsx}', // component src files
+  '**/src/*/*/*.{ts,tsx}', // child component src files
   'CODE_OF_CONDUCT.md',
   'LICENSE.md'
 ]
 
 const pathsToIgnore = [
   '**/macro.{js,ts}',
-  '**/*-loader.{js,ts}',
   '**/svg/**',
   'packages/*/README.md', // main package READMEs
   '**/packages/**/CHANGELOG.md',
   '**/config/**',
   '**/templates/**',
   '**/node_modules/**',
   '**/__docs__/**',
-  '**/__svg__/**',
+  '**/__build__/**',
   '**/__fixtures__/**',
   '**/__testfixtures__/**',
   '**/__tests__/**',
-  '**/__new-tests__/**',
-  '**/locales/**',
-  '**/styles.{js,ts}',
-  '**/theme.{js,ts}',
-  '**/props.ts',
-  '**/locator.{js,ts}',
-  '**/*Locator.{js,ts}',
-
+  '**/styles.{tsx,ts}',
+  '**/theme.{tsx,ts}',
   '**/types/**',
 
   // ignore index files that just re-export
-  '**/src/index.{js,ts}',
+  '**/src/index.ts',
 
   // packages to ignore:
   '**/canvas-theme/**',
@@ -106,7 +99,7 @@ const pathsToIgnore = [
   '**/ui-code-editor/src/CodeMirrorWrapper/**',
 
   // deprecated packages and modules:
-  '**/InputModeListener.{js,ts}',
+  '**/InputModeListener.ts',
   // regression testing app:
   '**/regression-test/**',
 ]
diff --git a/packages/__docs__/buildScripts/utils/getJSDoc.mts b/packages/__docs__/buildScripts/utils/getJSDoc.mts
@@ -105,7 +105,7 @@ function extractFunctionData(node: FunctionDeclaration | FunctionExpression | Ar
     description: description,
     ...(parameters.length > 0 && {params: parameters}),
     ...((genericParameters && genericParameters.length > 0) && {genericParameters: genericParameters}),
-    ...((returnsDesc || returnsType) && {
+    ...((returnsDesc || (returnsType && returnsType !== 'void')) && {
       returns: {
         description: returnsDesc,
         type: returnsType
@@ -131,7 +131,14 @@ function parseNode(node: ts.Node, typeChecker: TypeChecker): JsDocResult | undef
   }
 
   let result: JsDocResult | undefined = undefined
-  if (ts.isVariableStatement(node)) { // e.g. const x = function(){}, y = 5
+  if (ts.isVariableDeclaration(node)) { // e.g. x=1
+    if (node.initializer) {
+      if (ts.isArrowFunction(node.initializer) || ts.isFunctionExpression(node.initializer)) {
+        result = extractFunctionData(node.initializer, typeChecker)
+      }
+    }
+  }
+  else if (ts.isVariableStatement(node)) { // e.g. const x = function(){}, y = 5
     for (const d of node.declarationList.declarations) {
       if (d.initializer) {
         if (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer)) {
@@ -140,12 +147,11 @@ function parseNode(node: ts.Node, typeChecker: TypeChecker): JsDocResult | undef
       }
     }
   }
-  // e.g. function focusable(el: Element)
-  if (ts.isFunctionDeclaration(node)) {
+  else if (ts.isFunctionDeclaration(node)) { // e.g. function focusable(el: Element)
     result = extractFunctionData(node, typeChecker)
   }
   // if it's not a function, then try to parse types from the JSDoc comment
-  else if (!result) {
+  if (!result) {
     let description = ''
     const params: JsDocResult['params'] = []
     const docs = ts.getJSDocCommentsAndTags(node)
diff --git a/packages/debounce/src/debounce.ts b/packages/debounce/src/debounce.ts
@@ -23,8 +23,17 @@
  */
 
 interface DebounceOptions {
+  /**
+   * Specify invoking on the leading edge of the timeout
+   */
   leading?: boolean
+  /**
+   * The maximum time `func` is allowed to be delayed before it's invoked
+   */
   maxWait?: number
+  /**
+   * Specify invoking on the trailing edge of the timeout
+   */
   trailing?: boolean
 }
 
@@ -54,16 +63,10 @@ export type Debounced<F extends (...args: any) => any> = F & {
  *
  * @module debounce
  *
- * @param {Function} func The function to debounce.
- * @param {number} [wait=0] The number of milliseconds to delay.
- * @param {Object} [options={}] The options object.
- * @param {boolean} [options.leading=false]
- *  Specify invoking on the leading edge of the timeout.
- * @param {number} [options.maxWait]
- *  The maximum time `func` is allowed to be delayed before it's invoked.
- * @param {boolean} [options.trailing=true]
- *  Specify invoking on the trailing edge of the timeout.
- * @returns {Function} Returns the new debounced function.
+ * @param func The function to debounce.
+ * @param wait The number of milliseconds to delay.
+ * @param options options object.
+ * @returns Returns the new debounced function.
  */
 function debounce<F extends (...args: any) => any>(
   func: F,
diff --git a/packages/emotion/src/getComponentThemeOverride.ts b/packages/emotion/src/getComponentThemeOverride.ts
@@ -39,12 +39,12 @@ type ComponentName = keyof ComponentOverride | undefined
  * This is a utility function which calculates the correct component theme
  * based on every possible override there is.
 
- * @param {object} theme - Theme object
- * @param {*} displayName - Name of the component
- * @param {*} componentId - componentId of the component
- * @param {*} props - The component's props object
- * @param {*} componentTheme - The component's default theme
- * @returns {object} The calculated theme override object
+ * @param theme - Theme object
+ * @param displayName - Name of the component
+ * @param componentId - componentId of the component
+ * @param props - The component's props object
+ * @param componentTheme - The component's default theme
+ * @returns The calculated theme override object
  */
 const getComponentThemeOverride = (
   theme: ThemeOrOverride,
diff --git a/packages/ui-color-utils/src/alpha.ts b/packages/ui-color-utils/src/alpha.ts
@@ -30,9 +30,9 @@ import Color from 'tinycolor2'
  * ---
  * Adjust the alpha transparency of a color
  * @module alpha
- * @param {String} color
- * @param {Number} percent
- * @returns {String} color as rgb string
+ * @param color
+ * @param percent
+ * @returns color as rgb string
  */
 function alpha(color: string, percent: number): string {
   return Color(color)
diff --git a/packages/ui-color-utils/src/contrast.ts b/packages/ui-color-utils/src/contrast.ts
@@ -30,10 +30,10 @@ import Color from 'tinycolor2'
  * ---
  * check the contrast ratio of 2 colors. Optionally number of decimal places can be added
  * @module contrast
- * @param {String} color1
- * @param {String} color2
- * @param {Number} decimalPlaces
- * @returns {Number} color contrast ratio
+ * @param color1
+ * @param color2
+ * @param decimalPlaces
+ * @returns color contrast ratio
  */
 const contrast = (
   color1: string,
diff --git a/packages/ui-color-utils/src/conversions.ts b/packages/ui-color-utils/src/conversions.ts
@@ -27,17 +27,17 @@ import type { ColorInputWithoutInstance } from 'tinycolor2'
 
 /**
  * Converts any valid `TinyColor` colors to hex string
- * @param {ColorInputWithoutInstance} rgb a color string
- * @returns {String} a hex string like `#FF0000`
+ * @param rgb a color string
+ * @returns a hex string like `#FF0000`
  */
 const colorToHex = (rgb: ColorInputWithoutInstance): string => {
   return Color(rgb).toHexString().toUpperCase()
 }
 
 /**
  * Transforms any `TinyColor` to 8 length HEX (alpha included)
- * @param {ColorInputWithoutInstance} color representation from `TinyColor`
- * @returns {String} An 8 length hex string like `#FF0000FF`
+ * @param color representation from `TinyColor`
+ * @returns An 8 length hex string like `#FF0000FF`
  */
 const colorToHex8 = (color: ColorInputWithoutInstance): string => {
   return Color(color).toHex8String().toUpperCase()
@@ -46,8 +46,8 @@ const colorToHex8 = (color: ColorInputWithoutInstance): string => {
 /**
  * Transforms any `TinyColor` to RGBA object ( {r:number, g:number, b:number, a:number} )
  * also exported as `hexToRgb` for backward compatiblity reasons
- * @param {ColorInputWithoutInstance} color representation from `TinyColor`
- * @returns {Color.ColorFormats.RGBA} A `TinyColor` RGBA type
+ * @param color representation from `TinyColor`
+ * @returns A `TinyColor` RGBA type
  */
 const colorToRGB = (
   color: ColorInputWithoutInstance
@@ -57,8 +57,8 @@ const colorToRGB = (
 
 /**
  * Transforms any `TinyColor` to HSVA object ( {h:number, s:number, v:number, a:number} )
- * @param {ColorInputWithoutInstance} color representation from `TinyColor`
- * @returns {Color.ColorFormats.HSVA} A `TinyColor` HSVA type
+ * @param color representation from `TinyColor`
+ * @returns A `TinyColor` HSVA type
  */
 const colorToHsva = (
   color: ColorInputWithoutInstance
@@ -68,8 +68,8 @@ const colorToHsva = (
 
 /**
  * Transforms any `TinyColor` to HSLA object ( {h:number, s:number, l:number, a:number} )
- * @param {ColorInputWithoutInstance} color representation from `TinyColor`
- * @returns {Color.ColorFormats.HSLA} A `TinyColor` HSLA type
+ * @param color representation from `TinyColor`
+ * @returns  A `TinyColor` HSLA type
  */
 const colorToHsla = (
   color: ColorInputWithoutInstance
diff --git a/packages/ui-color-utils/src/validateContrast.ts b/packages/ui-color-utils/src/validateContrast.ts
@@ -49,7 +49,7 @@ interface ValidatedContrasts {
  *
  * @module validateContrast
  * @param contrast
- * @param validationLevel
+ * @param validationLevel WCAG 2.2 validation level
  * @returns validation object
  */
 const validateContrast = (
diff --git a/packages/ui-dom-utils/src/handleMouseOverOut.ts b/packages/ui-dom-utils/src/handleMouseOverOut.ts
@@ -36,8 +36,8 @@ import { contains } from './contains'
  * from one child element to another.
  *
  * @module handleMouseOverOut
- * @param handler {function} Callback function for handling the event
- * @param event {Event} The DOM Event that was fired
+ * @param handler Callback function for handling the event
+ * @param event The DOM Event that was fired
  */
 function handleMouseOverOut(
   handler: (event: React.MouseEvent) => void,
diff --git a/packages/ui-react-utils/src/ensureSingleChild.tsx b/packages/ui-react-utils/src/ensureSingleChild.tsx
@@ -35,9 +35,9 @@ import { safeCloneElement } from './safeCloneElement'
  * wrap in a span and return the child. Return null if child has
  * no length.
  * @module ensureSingleChild
- * @param {ReactNode} child
- * @param {Object} props - props for child
- * @returns {ReactElement|null} cloned instance for a single child, or children wrapped in a span
+ * @param child
+ * @param props props for child
+ * @returns cloned instance for a single child, or children wrapped in a span
  */
 function ensureSingleChild(child: ReactNode, props = {}) {
   const childCount = Children.count(child)
diff --git a/packages/ui-react-utils/src/getDisplayName.ts b/packages/ui-react-utils/src/getDisplayName.ts
@@ -31,8 +31,8 @@ import { ComponentType } from 'react'
  * Get the displayName of a React component.
  * needs a babel plugin to work https://github.com/facebook/react/issues/4915 !!
  * @module getDisplayName
- * @param {ComponentType|String} ReactComponent
- * @returns {String} the component displayName
+ * @param ReactComponent
+ * @returns the component displayName
  */
 function getDisplayName(ReactComponent: string | ComponentType) {
   return typeof ReactComponent === 'string'
diff --git a/packages/ui-react-utils/src/getElementType.ts b/packages/ui-react-utils/src/getElementType.ts
@@ -50,10 +50,10 @@ interface PropsObject {
  * 6. `<span>` if none of the above
  *
  * @module getElementType
- * @param {ComponentType} Component
- * @param {Object} props
- * @param {Function} getDefault an optional function that returns the default element type
- * @returns {String} the element type
+ * @param Component
+ * @param props
+ * @param getDefault an optional function that returns the default element type
+ * @returns the element type
  */
 function getElementType<T extends PropsObject>(
   Component: Omit<ComponentType<T>, 'propTypes'>,
diff --git a/packages/ui-react-utils/src/getInteraction.ts b/packages/ui-react-utils/src/getInteraction.ts
@@ -24,11 +24,23 @@
 
 export type GetInteractionOptions = {
   props?: {
+    /**
+     * specifies the interaction mode, one of 'enabled', 'disabled', or 'readonly'
+     */
     interaction?: InteractionType | null
+    /**
+     * specifies if the component is disabled. Will take precedence over readOnly
+     */
     disabled?: boolean | null
+    /**
+     * specifies if the component is readonly
+     */
     readOnly?: boolean | null
     [key: string]: any
   }
+  /**
+   * an array specifying the interaction types available to the component, ['disabled', 'readonly'] by default
+   */
   interactionTypes?: InteractionType[]
 }
 
@@ -41,13 +53,8 @@ export type InteractionType = 'enabled' | 'disabled' | 'readonly'
  * This is useful for form elements where consumers are able to either use the interaction prop as specified or the
  * native html disabled or readonly attributes
  * @module getInteraction
- * @param {Object} args
- * @param {Object} args.props - the component props
- * @param {string} args.props.interaction - specifies the interaction mode, one of 'enabled', 'disabled', or 'readonly'
- * @param {boolean} args.props.disabled - specifies if the component is disabled. Will take precedence over readOnly
- * @param {boolean} args.props.readOnly - specifies if the component is readonly
- * @param {Array} args.interactionTypes - an array specifying the interaction types available to the component, ['disabled', 'readonly'] by default
- * @returns {String} one of 'enabled', 'disabled', or 'readonly'
+ * @param args extra arguments
+ * @returns The calculated interaction type
  */
 export function getInteraction({
   props = {},
diff --git a/packages/ui-react-utils/src/matchComponentTypes.ts b/packages/ui-react-utils/src/matchComponentTypes.ts
@@ -33,9 +33,9 @@ import { ComponentType, ReactElement, ReactNode } from 'react'
  * specified types.
  *
  * @module matchComponentTypes
- * @param {ReactElement|any} componentInstance
- * @param {Array} types an array of React components
- * @returns {Boolean} true if the component matches at least one of the types
+ * @param componentInstance
+ * @param types an array of React components
+ * @returns true if the component matches at least one of the types
  */
 function matchComponentTypes<Type extends ReactElement = ReactElement>(
   componentInstance: ReactNode,
diff --git a/packages/ui-react-utils/src/pickProps.ts b/packages/ui-react-utils/src/pickProps.ts
@@ -28,10 +28,10 @@
  * ---
  * Return a props object with only specified propTypes.
  * @module pickProps
- * @param {Object} props React component props
- * @param {Object|Array<string>} propTypesOrAllowedPropList React component propTypes or the list of allowed prop keys
- * @param {Array} include an optional array of prop names to include
- * @returns {Object} props object with only the included props
+ * @param props React component props
+ * @param propTypesOrAllowedPropList React component propTypes or the list of allowed prop keys
+ * @param include an optional array of prop names to include
+ * @returns props object with only the included props
  * @module pickProps
  */
 function pickProps<T extends Record<string, any>>(
diff --git a/packages/ui-utils/src/createChainedFunction.ts b/packages/ui-utils/src/createChainedFunction.ts
@@ -34,8 +34,8 @@ type GenericFunction = (...args: any[]) => any
  *
  * Forked from: https://github.com/react-bootstrap/react-overlays/blob/master/src/utils/createChainedFunction.js
  * @module createChainedFunction
- * @param {function} funcs to chain
- * @returns {function|null}
+ * @param funcs Functions to chain. It can be null/undefined
+ * @returns the functions chained after each other
  */
 
 function createChainedFunction<F extends GenericFunction = GenericFunction>(

Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ interface ValidatedContrasts {`
`49`	`49`	`*`
`50`	`50`	`* @module validateContrast`
`51`	`51`	`* @param contrast`
`52`		`- * @param validationLevel`
	`52`	`+ * @param validationLevel WCAG 2.2 validation level`
`53`	`53`	`* @returns validation object`
`54`	`54`	`*/`
`55`	`55`	`const validateContrast = (`