When documenting React components using TypeScript and TSDoc, all props are described in the interface. This is necessary, among other things, so that utilities like Storybook create a table of arguments describing the props. The comment of the component itself usually contains a description and @example, which contains an example of how to use the component. Here's a code example:
/**
* Props for ExampleComponent.
*/
interface ExampleComponentProps {
/**
* The description for `PropertyA`.
*/
propertyA: string;
/**
* The description for `PropertyB`.
*/
propertyB: string;
/**
* The description for `PropertyC`.
*/
propertyC: number;
}
/**
* Component description.
*
* @example
* ```tsx
* <ExampleComponent ... />
* ```
*/
const ExampleComponent = ({ propertyA, propertyB, propertyC }: ExampleComponentProps) => {
return (
<div>
{propertyA}, {propertyB}, {propertyC}
</div>
);
};
export { ExampleComponent };
However, sometimes it is useful to use the inline documentation in the IDE, which usually appears when you hover your cursor over a component and it expects to display only the comment that is described for the component itself, no information about the props.
The first thing that comes to mind is to describe props information for the component, something like this:
/**
* Component description.
*
* @param propertyA - The description for `PropertyA`.
* @param propertyB - The description for `PropertyB`.
* @param propertyC - The description for `PropertyC`.
*
* @example
* ```tsx
* <ExampleComponent ... />
* ```
*/
const ExampleComponent = ({ propertyA, propertyB, propertyC }: ExampleComponentProps) => {
return (
<div>
{propertyA}, {propertyB}, {propertyC}
</div>
);
};
The inline documentation then displays all the information you need, but this leads to duplicate comments, which seems like a very bad idea.
I tried using @inheritDoc, but this also did not produce the expected result.
Inline documentation does not support documentation inheritance via this tag.
Perhaps there are some plugins or extensions that add this functionality to VSCode, Webstorm?
What good documentation practices exist for React components to have good support for inline documentation, as well as good support for services to generate documentation based on comments, and how can we avoid duplicate comments?