Improving docs: More detailed / helpful JSDocs for components

[bubulux]

To start: I like the library and generally have no issues with the docs in the Storybook, for exploring styles/options, etc...

But, I often find myself in a situation, where I precisely know what I need, but I don't have the exact props API in my head, which forces me to opt out of my editor and go into the storybook.

In that case, it would be helpful to have more detailed JSDocs comments. Mostly that is the most you get:

/**
 * Buttons give people a way to trigger an action.
 */
export declare const Button: ForwardRefComponent<ButtonProps>;

In essence, I would find it helpful:

• when the core props for the given component were listed with a sentence describing their purpose (in some cases there are props that only work in relation to one another, like with typography wrap and truncation option, here it would be also beneficial to have quirks like this as a quick note in the JSDocs)
• when the defaults of the listed props are mentioned
• when the component strongly relates to other components (like TabsList relates to Tab) it would be beneficial to also list these related components

As a simple example the Button docs, what I could imagine would be a good start.

/**
 * @description Buttons give people a way to trigger an action.
 *
 * @props
 * - `icon`: Icon that renders either before or after the `children` as specified by the `iconPosition` prop.
 * - `iconPosition`: A button can format its icon to appear before or after its content.
 * - `appearance`: A button can have its content and borders styled for greater emphasis or to be subtle.
 * - `shape`: A button can be rounded, circular, or square.
 * - `size`: A button supports different sizes.
 * - `disabled`: A button can show that it cannot be interacted with.
 * - `disabledFocusable`: When set, allows the button to be focusable even when it has been disabled.
 * - `as`: The root tag to use to render this button.
 *
 * @default iconPosition='before' appearance='secondary' shape='rounded' size='medium' disabled=false disabledFocusable=false
 */
export declare const Button: ForwardRefComponent<ButtonProps>;

In essence, this is just a suggestion and I am open to better solutions for these "at-a-glance docs". AND: I would be glad to write and contribute these docs.

What do other users of the library think of that? Would this be also useful to you?

Best, Sam

[spmonahan]

Adding the docs as you describe would be redundant as all this information exists in the .types.ts file. Here's the Button types as an example: https://github.com/microsoft/fluentui/blob/master/packages/react-components/react-button/library/src/components/Button/Button.types.ts

The benefit of having this information in types is that Typescript can use it to provide Intellisense in editors like VSCode in addition to providing static type checking.

Adding the documentation you propose will increase the documentation burden on the library and increase the likelihood that the docs drift over time as there would be two sources of truth.