Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Conversation

aarongarciah
Copy link
Member

@aarongarciah aarongarciah commented May 17, 2024

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.
      image
  • 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).
    deploy-preview-42280--material-ui netlify app_material-ui_react-hidden_
    deploy-preview-42280--material-ui netlify app_material-ui_react-hidden_ (1)
  • 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.

@aarongarciah aarongarciah added docs Improvements or additions to the documentation proof of concept Studying and/or experimenting with a to be validated approach labels May 17, 2024
@mui-bot
Copy link

mui-bot commented May 17, 2024

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

@aarongarciah aarongarciah force-pushed the aarongarcia/support-jsdoc-deprecated-components branch from c34468e to 16d2b82 Compare May 17, 2024 16:25
@aarongarciah aarongarciah changed the title [POC][docs] Display deprecation messages in API pages [POC][docs] JSDoc comments as deprecation source of truth May 17, 2024
@alexfauquette
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member

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:

@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
Copy link
Member Author

aarongarciah commented May 21, 2024

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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation proof of concept Studying and/or experimenting with a to be validated approach
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants