Allow JSDoc tags in components

packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts

@@ -11,6 +11,7 @@ import type { Link } from 'mdast';
 import { defaultHandlers, parse as docgenParse, ReactDocgenApi } from 'react-docgen';
 import { renderMarkdown } from '@mui/internal-markdown';
 import { ComponentClassDefinition } from '@mui/internal-docs-utils';
+import { parse as parseDoctrine, Annotation } from 'doctrine';
 import { ProjectSettings, SortingStrategiesType } from '../ProjectSettings';
 import { ComponentInfo, toGitHubPath, writePrettifiedFile } from '../buildApiUtils';
 import muiDefaultPropsHandler from '../utils/defaultPropsHandler';
@@ -147,7 +148,7 @@ export async function computeApiDescription(
  *  *
  *  * - [Icon API](https://mui.com/api/icon/)
  */
-async function annotateComponentDefinition(api: ReactApi) {
+async function annotateComponentDefinition(api: ReactApi, componentJsdoc: Annotation) {
   const HOST = 'https://mui.com';
 
   const typesFilename = api.filename.replace(/\.js$/, '.d.ts');
@@ -318,6 +319,14 @@ async function annotateComponentDefinition(api: ReactApi) {
     markdownLines.push(`- inherits ${inheritanceAPILink}`);
   }
 
+  if (componentJsdoc.tags.length > 0) {
+    markdownLines.push('');
+  }
+
+  componentJsdoc.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 */`;
@@ -738,13 +747,19 @@ export default async function generateComponentApi(
     reactApi.props = {};
   }
 
+  const { getComponentImports = defaultGetComponentImports } = projectSettings;
+  const componentJsdoc = parseDoctrine(reactApi.description);
+
+  // We override `reactApi.description` with `componentJsdoc.description` because
+  // the former can include JSDoc tags that we don't want to render in the docs.
+  reactApi.description = componentJsdoc.description;
+
   // Ignore what we might have generated in `annotateComponentDefinition`
   const annotatedDescriptionMatch = reactApi.description.match(/(Demos|API):\r?\n\r?\n/);
   if (annotatedDescriptionMatch !== null) {
     reactApi.description = reactApi.description.slice(0, annotatedDescriptionMatch.index).trim();
   }
 
-  const { getComponentImports = defaultGetComponentImports } = projectSettings;
   reactApi.filename = filename;
   reactApi.name = componentInfo.name;
   reactApi.imports = getComponentImports(componentInfo.name, filename);
@@ -793,7 +808,7 @@ export default async function generateComponentApi(
   attachTranslations(reactApi, projectSettings.propsSettings);
 
   // eslint-disable-next-line no-console
-  console.log('Built API docs for', reactApi.apiPathname);
+  // console.log('Built API docs for', reactApi.apiPathname);
 
   if (!componentInfo.skipApiGeneration) {
     const {
@@ -825,7 +840,7 @@ export default async function generateComponentApi(
         : !skipAnnotatingComponentDefinition
     ) {
       // Add comment about demo & api links (including inherited component) to the component file
-      await annotateComponentDefinition(reactApi);
+      await annotateComponentDefinition(reactApi, componentJsdoc);
     }
   }
 

packages/mui-material/src/Hidden/Hidden.d.ts

@@ -90,6 +90,8 @@ export interface HiddenProps {
  * API:
  *
  * - [Hidden API](https://mui.com/material-ui/api/hidden/)
+ *
+ * @deprecated The Hidden component was deprecated in Material UI v5. To learn more, see [the Hidden section](/material-ui/migration/v5-component-changes/#hidden) of the migration docs.
  */
 declare const Hidden: React.JSXElementConstructor<HiddenProps>;
 

packages/mui-material/src/Hidden/Hidden.js

@@ -6,6 +6,8 @@ import HiddenCss from './HiddenCss';
 
 /**
  * Responsively hides children based on the selected implementation.
+ *
+ * @deprecated The Hidden component was deprecated in Material UI v5. To learn more, see [the Hidden section](/material-ui/migration/v5-component-changes/#hidden) of the migration docs.
  */
 function Hidden(props) {
   const {