[docs-infra] Allow JSDoc tags

[aarongarciah]

These changes allow JSDoc tags like @deprecated to be present in components and hook JSDoc comments without them being displayed in the docs. Before these changes, JSDoc tags would be displayed in the docs.

The benefits to allow JSDoc tags are:

• Consumers get the info right in their IDE e.g. strikethrough styles and info in the popover when using a @deprecated API.
  
• We'll be able to use JSDoc tags like @deprecated as the source of truth to display deprecation alerts in API pages. Further context #42280
• We'll be able to use standard JSDoc syntax for things like links to doc pages.

[mui-bot]

Netlify deploy preview

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

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 9611931

[alexfauquette]

From what I understand, you parse the JSDocs to do a distinction between the description and tag, and then render the enriched message and add the tags at the end

Looks clean ✅

[alexfauquette]

The docs API generation is using naming template to find the types to parse. That's why currently have wrong parameter table 🙈

material-ui/packages/api-docs-builder/ApiBuilders/HookApiBuilder.ts

Lines 547 to 549 in bfcb0b6

	const parameters = await extractInfoFromType(`${upperFirst(name)}Parameters`, project);
	const returnValue = await extractInfoFromType(`${upperFirst(name)}ReturnValue`, project);

[aarongarciah]

I saw this, yeah! I was about to open an issue about it. It looks like some hooks like useMenuItemContextStabilizer and useOptionContextStabilizer are missing the *Parameters and *ReturnValue types. But even if they had those types, it looks like the API generation for the parameter table in hooks only works for hooks that accept a single object parameter. Same for the return value.

We also need to improve how we display the parameters table in the docs since it's not clear that the hook accepts a single object vs separated parameters when looking at it.

[oliviertassinari]

It feels like the script generation should crash in those cases: https://next--material-ui.netlify.app/base-ui/react-menu/hooks-api/#use-menu-item-context-stabilizer. Forcing to either make the API private, or to use the right naming convention for its type.

[aarongarciah]

From what I understand, you parse the JSDocs to do a distinction between the description and tag, and then render the enriched message and add the tags at the end

@alexfauquette exactly! Side note: doctrine is a dead project but we still use it on some docs infra stuff.

[cherniavskii]

Shouldn't we use absolute URLs here for links to work in IDE?

[aarongarciah]

Yes, we should use absolute URLs for links inside comments, but this is an existing issue that needs to be tackled separately. We have this problem in all props e.g. https://github.com/mui/material-ui/blob/next/packages/mui-material/src/ListItem/ListItem.js#L372

JSDoc comments are used to generate the docs so we can't assume we're always in https://mui.com. See: https://github.com/mui/material-ui/blob/master/packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts#L111-L117

We should probably use absolute URLs and adjust the docs infra to replace the base URL with the correct one. I'll open an issue.

[DiegoAndai]

@cherniavskii good catch!

@aarongarciah please assign me to the issue when you create it 😊

[aarongarciah]

@DiegoAndai done! #42361