-
-
Notifications
You must be signed in to change notification settings - Fork 32k
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
[docs-infra] Allow JSDoc tags #42327
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,5 @@ | ||
{ | ||
"hookDescription": "Stabilizes the ListContext value for the MenuItem component, so it doesn't change when sibling items update.\n\n@param id The id of the MenuItem. If undefined, it will be generated with useId.\n@returns The stable ListContext value and the id of the MenuItem.", | ||
"hookDescription": "Stabilizes the ListContext value for the MenuItem component, so it doesn't change when sibling items update.", | ||
"parametersDescriptions": {}, | ||
"returnValueDescriptions": {} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,5 @@ | ||
{ | ||
"hookDescription": "Stabilizes the ListContext value for the Option component, so it doesn't change when sibling Options update.\n\n@param value The value of the Option.\n@returns The stable ListContext value.", | ||
"hookDescription": "Stabilizes the ListContext value for the Option component, so it doesn't change when sibling Options update.", | ||
"parametersDescriptions": {}, | ||
"returnValueDescriptions": {} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Shouldn't we use absolute URLs here for links to work in IDE? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @cherniavskii good catch! @aarongarciah please assign me to the issue when you create it 😊 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @DiegoAndai done! #42361 |
||
*/ | ||
declare const Hidden: React.JSXElementConstructor<HiddenProps>; | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I saw this, yeah! I was about to open an issue about it. It looks like some hooks like
useMenuItemContextStabilizer
anduseOptionContextStabilizer
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.