Allow JSDoc tags in hooks

mui · May 22, 2024 · fa4a14b · fa4a14b
1 parent 0748b2e
commit fa4a14b
Show file tree

Hide file tree

Showing 5 changed files with 24 additions and 10 deletions.
diff --git a/...nslations/api-docs/use-menu-item-context-stabilizer/use-menu-item-context-stabilizer.json b/...nslations/api-docs/use-menu-item-context-stabilizer/use-menu-item-context-stabilizer.json
@@ -1,5 +1,5 @@
 {
-  "hookDescription": "Stabilizes the ListContext value for the MenuItem component, so it doesn't change when sibling items update.\n\n@param id The id of the MenuItem. If undefined, it will be generated with useId.\n@returns The stable ListContext value and the id of the MenuItem.",
+  "hookDescription": "Stabilizes the ListContext value for the MenuItem component, so it doesn't change when sibling items update.",
   "parametersDescriptions": {},
   "returnValueDescriptions": {}
 }
diff --git a/docs/translations/api-docs/use-option-context-stabilizer/use-option-context-stabilizer.json b/docs/translations/api-docs/use-option-context-stabilizer/use-option-context-stabilizer.json
@@ -1,5 +1,5 @@
 {
-  "hookDescription": "Stabilizes the ListContext value for the Option component, so it doesn't change when sibling Options update.\n\n@param value The value of the Option.\n@returns The stable ListContext value.",
+  "hookDescription": "Stabilizes the ListContext value for the Option component, so it doesn't change when sibling Options update.",
   "parametersDescriptions": {},
   "returnValueDescriptions": {}
 }
diff --git a/packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts b/packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts
@@ -8,6 +8,7 @@ import traverse from '@babel/traverse';
 import { defaultHandlers, parse as docgenParse, ReactDocgenApi } from 'react-docgen';
 import kebabCase from 'lodash/kebabCase';
 import upperFirst from 'lodash/upperFirst';
+import { parse as parseDoctrine, Annotation } from 'doctrine';
 import { renderMarkdown } from '@mui/internal-markdown';
 import { ProjectSettings } from '../ProjectSettings';
 import { computeApiDescription } from './ComponentApiBuilder';
@@ -108,7 +109,7 @@ export interface ReactApi extends ReactDocgenApi {
  * *
  * * - [useButton API](https://mui.com/base-ui/api/use-button/)
  */
-async function annotateHookDefinition(api: ReactApi) {
+async function annotateHookDefinition(api: ReactApi, hookJsdoc: Annotation) {
   const HOST = 'https://mui.com';
 
   const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
@@ -285,6 +286,14 @@ async function annotateHookDefinition(api: ReactApi) {
     })`,
   );
 
+  if (hookJsdoc.tags.length > 0) {
+    markdownLines.push('');
+  }
+
+  hookJsdoc.tags.forEach((tag) => {
+    markdownLines.push(`@${tag.title}${tag.name ? ` ${tag.name} -` : ''} ${tag.description}`);
+  });
+
   const jsdoc = `/**\n${markdownLines
     .map((line) => (line.length > 0 ? ` * ${line}` : ` *`))
     .join('\n')}\n */`;
@@ -546,6 +555,11 @@ export default async function generateHookApi(
 
   const parameters = await extractInfoFromType(`${upperFirst(name)}Parameters`, project);
   const returnValue = await extractInfoFromType(`${upperFirst(name)}ReturnValue`, project);
+  const hookJsdoc = parseDoctrine(reactApi.description);
+
+  // We override `reactApi.description` with `hookJsdoc.description` because
+  // the former can include JSDoc tags that we don't want to render in the docs.
+  reactApi.description = hookJsdoc.description;
 
   // Ignore what we might have generated in `annotateHookDefinition`
   const annotatedDescriptionMatch = reactApi.description.match(/(Demos|API):\r?\n\r?\n/);
@@ -588,7 +602,7 @@ export default async function generateHookApi(
     await generateApiJson(apiPagesDirectory, reactApi);
 
     // Add comment about demo & api links to the component hook file
-    await annotateHookDefinition(reactApi);
+    await annotateHookDefinition(reactApi, hookJsdoc);
   }
 
   return reactApi;

diff --git a/packages/mui-base/src/useMenuItem/useMenuItemContextStabilizer.ts b/packages/mui-base/src/useMenuItem/useMenuItemContextStabilizer.ts
@@ -6,16 +6,16 @@ import { ListContext, ListContextValue, ListItemState } from '../useList';
 /**
  * Stabilizes the ListContext value for the MenuItem component, so it doesn't change when sibling items update.
  *
- * @param id The id of the MenuItem. If undefined, it will be generated with useId.
- * @returns The stable ListContext value and the id of the MenuItem.
- *
  * Demos:
  *
  * - [Menu](https://mui.com/base-ui/react-menu/#hooks)
  *
  * API:
  *
  * - [useMenuItemContextStabilizer API](https://mui.com/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer)
+ *
+ * @param id - The id of the MenuItem. If undefined, it will be generated with useId.
+ * @returns The stable ListContext value and the id of the MenuItem.
  */
 export function useMenuItemContextStabilizer(id: string | undefined) {
   const listContext = React.useContext(ListContext as React.Context<ListContextValue<string>>);

diff --git a/packages/mui-base/src/useOption/useOptionContextStabilizer.ts b/packages/mui-base/src/useOption/useOptionContextStabilizer.ts
@@ -5,16 +5,16 @@ import { ListContext, ListContextValue } from '../useList';
 /**
  * Stabilizes the ListContext value for the Option component, so it doesn't change when sibling Options update.
  *
- * @param value The value of the Option.
- * @returns The stable ListContext value.
- *
  * Demos:
  *
  * - [Select](https://mui.com/base-ui/react-select/#hooks)
  *
  * API:
  *
  * - [useOptionContextStabilizer API](https://mui.com/base-ui/react-select/hooks-api/#use-option-context-stabilizer)
+ *
+ * @param value - The value of the Option.
+ * @returns The stable ListContext value.
  */
 export function useOptionContextStabilizer<OptionValue>(value: OptionValue) {
   const listContext = React.useContext(ListContext as React.Context<ListContextValue<OptionValue>>);