[POC][docs] JSDoc comments as deprecation source of truth

docs/pages/material-ui/api/hidden.json

@@ -40,5 +40,7 @@
   "filename": "/packages/mui-material/src/Hidden/Hidden.js",
   "inheritance": null,
   "demos": "<ul><li><a href=\"/material-ui/react-hidden/\">Hidden</a></li></ul>",
-  "cssComponent": false
+  "cssComponent": false,
+  "deprecated": true,
+  "deprecationInfo": "The Hidden component was deprecated in Material UI v5. To learn more, see <a href=\"/material-ui/migration/v5-component-changes/#hidden\">the Hidden section</a> of the migration docs."
 }

docs/src/modules/components/ApiPage.js

@@ -6,6 +6,7 @@ import Typography from '@mui/material/Typography';
 import AdGuest from 'docs/src/modules/components/AdGuest';
 import Alert from '@mui/material/Alert';
 import VerifiedRoundedIcon from '@mui/icons-material/VerifiedRounded';
+import DangerousIcon from '@mui/icons-material/Dangerous';
 import { alpha } from '@mui/material/styles';
 import { useTranslate, useUserLanguage } from '@mui/docs/i18n';
 import { HighlightedCode } from '@mui/docs/HighlightedCode';
@@ -79,6 +80,8 @@ export default function ApiPage(props) {
     spread,
     slots: componentSlots,
     classes,
+    deprecated,
+    deprecationInfo,
   } = pageContent;
 
   const componentClasses = Array.isArray(classes)
@@ -180,56 +183,96 @@ export default function ApiPage(props) {
     >
       <MarkdownElement>
         <h1>{pageContent.name} API</h1>
-        <Typography variant="h5" component="p" className="description" gutterBottom>
-          {description}
-          {disableAd ? null : (
-            <BrandingProvider>
-              <AdGuest>
-                <Ad />
-              </AdGuest>
-            </BrandingProvider>
-          )}
-        </Typography>
-        <Heading hash="demos" />
-        <Alert
-          severity="success"
-          variant="outlined"
-          icon={<VerifiedRoundedIcon sx={{ fontSize: 20 }} />}
-          sx={[
-            (theme) => ({
+        {deprecated ? (
+          <Alert
+            severity="error"
+            variant="outlined"
+            icon={<DangerousIcon sx={{ fontSize: 20 }} />}
+            sx={(theme) => ({
               mt: 1.5,
-              pt: 1,
-              px: 2,
-              pb: 0,
+              mb: 1.5,
               fontSize: theme.typography.pxToRem(16),
-              backgroundColor: (theme.vars || theme).palette.success[50],
-              borderColor: (theme.vars || theme).palette.success[100],
+              backgroundColor: (theme.vars || theme).palette.error[50],
+              borderColor: (theme.vars || theme).palette.error[100],
               '& .MuiAlert-message': {
                 '& * p': {
                   color: (theme.vars || theme).palette.text.primary,
                   mb: 1,
                 },
                 '& * a': {
                   fontWeight: theme.typography.fontWeightMedium,
-                  color: (theme.vars || theme).palette.success[900],
-                  textDecorationColor: alpha(theme.palette.success[600], 0.3),
+                  color: (theme.vars || theme).palette.error[900],
+                  textDecorationColor: alpha(theme.palette.error[600], 0.3),
                 },
               },
               ...theme.applyDarkStyles({
-                backgroundColor: alpha(theme.palette.success[700], 0.12),
-                borderColor: alpha(theme.palette.success[400], 0.1),
+                backgroundColor: alpha(theme.palette.error[700], 0.12),
+                borderColor: alpha(theme.palette.error[400], 0.1),
                 '& .MuiAlert-message': {
                   ul: {
                     pl: 3,
                   },
                   '& * a': {
-                    color: (theme.vars || theme).palette.success[100],
-                    textDecorationColor: alpha(theme.palette.success[100], 0.3),
+                    color: (theme.vars || theme).palette.error[100],
+                    textDecorationColor: alpha(theme.palette.error[100], 0.3),
                   },
                 },
               }),
+            })}
+          >
+            <span
+              dangerouslySetInnerHTML={{
+                __html: deprecationInfo,
+              }}
+            />
+          </Alert>
+        ) : null}
+        <Typography variant="h5" component="p" className="description" gutterBottom>
+          {description}
+          {disableAd ? null : (
+            <BrandingProvider>
+              <AdGuest>
+                <Ad />
+              </AdGuest>
+            </BrandingProvider>
+          )}
+        </Typography>
+        <Heading hash="demos" />
+        <Alert
+          severity="success"
+          variant="outlined"
+          icon={<VerifiedRoundedIcon sx={{ fontSize: 20 }} />}
+          sx={(theme) => ({
+            mt: 1.5,
+            pb: 0,
+            fontSize: theme.typography.pxToRem(16),
+            backgroundColor: (theme.vars || theme).palette.success[50],
+            borderColor: (theme.vars || theme).palette.success[100],
+            '& .MuiAlert-message': {
+              '& * p': {
+                color: (theme.vars || theme).palette.text.primary,
+                mb: 1,
+              },
+              '& * a': {
+                fontWeight: theme.typography.fontWeightMedium,
+                color: (theme.vars || theme).palette.success[900],
+                textDecorationColor: alpha(theme.palette.success[600], 0.3),
+              },
+            },
+            ...theme.applyDarkStyles({
+              backgroundColor: alpha(theme.palette.success[700], 0.12),
+              borderColor: alpha(theme.palette.success[400], 0.1),
+              '& .MuiAlert-message': {
+                ul: {
+                  pl: 3,
+                },
+                '& * a': {
+                  color: (theme.vars || theme).palette.success[100],
+                  textDecorationColor: alpha(theme.palette.success[100], 0.3),
+                },
+              },
             }),
-          ]}
+          })}
         >
           <span
             dangerouslySetInnerHTML={{

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';
@@ -52,6 +53,8 @@ export interface ReactApi extends ReactDocgenApi {
   muiName: string;
   description: string;
   spread: boolean | undefined;
+  deprecated: true | undefined;
+  deprecationInfo: string | undefined;
   /**
    * If `true`, the component supports theme default props customization.
    * If `null`, we couldn't infer this information.
@@ -147,7 +150,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 +321,10 @@ async function annotateComponentDefinition(api: ReactApi) {
     markdownLines.push(`- inherits ${inheritanceAPILink}`);
   }
 
+  componentJsdoc.tags.forEach((tag) => {
+    markdownLines.push('', `@${tag.title} ${tag.description}`);
+  });
+
   const jsdoc = `/**\n${markdownLines
     .map((line) => (line.length > 0 ? ` * ${line}` : ` *`))
     .join('\n')}\n */`;
@@ -400,6 +407,8 @@ const generateApiPage = async (
       .map((item) => `<li><a href="${item.demoPathname}">${item.demoPageTitle}</a></li>`)
       .join('\n')}</ul>`,
     cssComponent: cssComponents.indexOf(reactApi.name) >= 0,
+    deprecated: reactApi.deprecated,
+    deprecationInfo: reactApi.deprecationInfo,
   };
 
   const { classesSort = sortAlphabetical('key'), slotsSort = null } = {
@@ -738,13 +747,24 @@ 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 includes JSDoc tags that we don't want to render in the API page.
+  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;
+  const deprecation = componentJsdoc.tags.find((tag) => tag.title === 'deprecated');
+
+  reactApi.deprecated = !!deprecation || undefined;
+  reactApi.deprecationInfo = renderMarkdown(deprecation?.description || '') || undefined;
+
   reactApi.filename = filename;
   reactApi.name = componentInfo.name;
   reactApi.imports = getComponentImports(componentInfo.name, filename);
@@ -825,7 +845,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 {