docs(props): remove jsdoc typedefs for props #641
Conversation
We prefer to use React doc strings to document props, as that is what most of the tools in the React ecosystem expects, e.g. Storybook and React docgen. Having JSDoc typedefs in additon means that we have two keep two documentation styles in sync with the prop changes. A follow-up for some components may be required to add relevant React docstrings to props where we used to have typedefs coverage.
We align with the way react-docgen extracts information from our
components, and that means that we can strip out our JSDoc strings. In a
lot of places they are stale, and in most cases they follow a format
that is not necessary for us.
Instead we can use a simpler format:
/**
* General component description.
*/
const Component = ({ foo, bar }) => (...)
Component.propTypes = {
/**
* multi-line description
* of prop "foo"
*/
foo: PropTypes.number,
/** single-line description of prop "bar" */
bar: PropTypes.number,
}
This should be enough for most cases and tools that build on
react-docgen.
|
Test summary
Run details
View run in Cypress Dashboard ➡️ This comment has been generated by cypress-bot as a result of this project's GitHub integration settings. You can manage this integration in this project's settings in the Cypress Dashboard |
There was a problem hiding this comment.
This just reduced our maintenance burden by ~:infinity:!
Thank you 😄
I think we might also want to remove this:
ui/components/organisation-unit-tree/src/organisation-unit-tree.js
Lines 144 to 155 in 9e1dbf8
Good catch ! |
|
The Transfer, FileInput, and OrganisationUnitTree uses JSDoc strings for helper functions, and I have left those because they make the functions a lot easier to understand. Note that these are not Components, so using JSDoc here is alright. |
We prefer to use React doc strings to document props, as that is what
most of the tools in the React ecosystem expects, e.g. Storybook and
React docgen.
Having JSDoc typedefs in additon means that we have two keep two
documentation styles in sync with the prop changes.
A follow-up for some components may be required to add relevant React
docstrings to props where we used to have typedefs coverage.