Addon-docs: Support jsdoc params to describe function signature #8660
Conversation
|
This pull request is being automatically deployed with ZEIT Now (learn more). 🔍 Inspect: https://zeit.co/storybook/monorepo/95435c2m3 |
|
I am not sure how I ended up with all those changes to the I only changed the stories. |
|
@patricklafrance This is amazing work. 🥇 The changes are there because you started on my branch, which already upgraded I'll review it all properly today or this weekend, but at first glance it looks superb!!! |
shilman
changed the title
shilman
changed the title
| @@ -59,6 +60,9 @@ | |||
| "ts-dedent": "^1.1.0" | |||
| }, | |||
| "devDependencies": { | |||
| "@types/doctrine": "^0.0.3", | |||
| "@types/enzyme": "^3.10.3", | |||
There was a problem hiding this comment.
Without those types I couldn't compile the app with yarn bootstrap
| ? propsFromDocgen(processedType, section) | ||
| : propsFromPropTypes(processedType, section); | ||
|
|
||
| return extractPropsFromDocgen(processedType, section); |
There was a problem hiding this comment.
Is propsFromPropTypes unused? Is this a breaking change?
There was a problem hiding this comment.
Nvm, I see it below. Is this tested?
| [TypeSystem.Unknown]: unknownHandler, | ||
| }; | ||
|
|
||
| export const getPropTypeSystem = (docgenInfo: DocgenInfo): string => { |
shilman
deleted the
8532-support-jsdocs-params-to-describe-js-function-signature
branch
Issue: #8532
What I did
This PR add JSDoc support to describe the signature of a function in the docs addon props table when using PropTypes.
When a prop type is defined as a function, if the optional JSDoc is provided, the type of the prop will be a function signature infered from the JSDoc @param and @returns tags instead of being hardcoded to "func".
The support for @param and @returns follow the JSDoc specs:
https://jsdoc.app/tags-param.html
https://jsdoc.app/tags-returns.html
This PR is a base for other issues and enhancement that will be tackled soon.
There is a few considerations that you should be aware of...
Limitations:
A property description cannot start with a @.
This means that for the property:
The description would be empty.
When @ is in the body of the description it's fine.
Would display: onClick @description@
JSDoc parser:
To parse the JSDoc, I found 2 popular packages: https://www.npmjs.com/package/doctrine and https://www.npmjs.com/package/comment-parser
doctrine is obviously the most popular one with 14 millions weekly downloads. Sadly, it has been deprecated a few months ago.
The ESLint team decided to stop supporting rules to validate JSDoc format.
comment-parser is an interesting option but it doesn't work in a web environment, it has a dependency on node fs.
I decided to use doctrine even if it's deprecated since it's still widely use and is stable. I don't think we will end up supporting something else than @param, @returns and @ignore which works fine with doctrine. I dont see the JSDoc specs change for those tag in a near future.
Parsing the JSDoc:
To ensure good perfomance, the JSDoc tags should probably be parsed at compile time with a babel plugin. To get something out quickly I parse them from the Props React component.
Performance seems acceptable for now. 3 tables of 50 props having JSDoc tags render instantly in dev. A test is available in the cra-ts-kitchen-sink.
What's next?
How to test
yarn jest --testPathPattern=type-system-handlers --watchcra-ts-kitchen-sinkunder the story "docgen/Props types/jsdoc-perfo"cra-ts-kitchen-sinkunder the story "docgen/Props types/jsdoc"