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

[aarongarciah]

As of today, we don't show deprecation messages in component API pages. The general idea of this PR is to treat JSDoc comments as the source of truth to mark components as deprecated in the docs.

• Adds support for @deprecated JSDoc tags (and any other tag) in components.
  • Before these changes, we couldn't annotate components with JSDoc tags because tags would appear on API pages.
• The deprecation message from JSDoc appears automatically on API pages.
  • For now, it works in Material, Joy, and System component API pages. It doesn't work on markdown-based pages i.e. it doesn't work on Base pages, which combines usage and API on the same page and it's markdown-based.
    
• JSDoc tags are properly copied from .js to .d.ts files (using the existing mechanism).
• Consumers will be able to see components as deprecated in their IDEs (although a long-standing TS issue sometimes interferes with the strikethrough styles).

Preview link: https://deploy-preview-42280--material-ui.netlify.app/material-ui/api/hidden/

---

Potential improvements:

• Apply changes to hooks and other APIs.
• [Unrelated] We have two similar but different-looking alerts in the docs, one used in usage pages (markdown rendered) and the other one in API pages (Material UI's Alert with some customization on top).
  
  
• edit: discarded, not worth the complexity. Use JSDoc as the source of truth for the deprecation message in markdown-generated pages, too, so it would work in all markdown-based pages too, like Base pages.
  • Right now, deprecation messages are hardcoded in .md files (example).
  • It would require some work to include the deprecation alert in the middle of markdown-generated pages since the whole page is rendered as a single markdown block, but definitely doable.

[mui-bot]

Netlify deploy preview

https://deploy-preview-42280--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 16d2b82

[alexfauquette]

Looks promising 👍 Quick note: the text are usually stored in a translation files even if we do not support translation yet.

Use JSDoc as the source of truth for the deprecation message in markdown-generated pages, too, so it would work in all markdown-based pages too, like Base pages.

This might be harder since it's not a one to one relation ship. For example when you will deprecate one of the List sub component.

Not sure the time spent on using JSDocs to show warning in Demo pages is worth compared to doing a copy/paste which add more flexibility (for ex: putting the warning in the section that introduce the subcomponent instead of the header)

[aarongarciah]

Quick note: the text are usually stored in a translation files even if we do not support translation yet.

I'm assuming we'll need to duplicate the deprecated message in the JSDoc and the translation file. In that case, I'm not sure using JSDoc as the source of truth to display the deprecated message in the API page makes sense. What still makes sense is allowing the usage of JSDoc tags in components/hooks so consumers receive that in their IDE.

This might be harder since it's not a one to one relation ship. For example when you will deprecate one of the List sub component.
Not sure the time spent on using JSDocs to show warning in Demo pages is worth compared to doing a copy/paste which add more flexibility (for ex: putting the warning in the section that introduce the subcomponent instead of the header)

Probably not worth it, yeah. btw, do we have translations in md files?

[alexfauquette]

I'm assuming we'll need to duplicate the deprecated message in the JSDoc and the translation file.

To be clear, translation files are generated from the JSDocs by pnpm docs:api:

• https://github.com/mui/material-ui/blob/master/docs/pages/material-ui/api/hidden.json
• https://github.com/mui/material-ui/blob/master/docs/translations/api-docs/hidden/hidden.json

@michaldudak recently worked on cleaning this pipeline

btw, do we have translations in md files?

Not sure. Translation got removed when I joined (2 years ago) If I remember correctly, it was done by using markdown files with xxx-pt.md, xxx-zh.md formats

[aarongarciah]

Thanks for the input @alexfauquette. I'll go ahead and separate this PR into two:

1. Allow JSDoc tags in components and hooks JSDoc comments.
2. Automate displaying deprecation messages in API pages (including writing deprecation messages in translation files).