Inline Component Prop Documentation

[michaelhabib15]

🚀 Feature Proposal

Making a request for inline dev documentation around components and component props.

Motivation

This is extremely helpful for developers when using canvas components, as it allows devs to see clear documentation around each prop in the exported .d file with a simple click in their IDE, without having to refer to the online documentation.

There is also the case where the storybook documentation was omitting certain prop documentation that I describe below.

Example

I ran into a confusing issue when trying to use RadioGroup and Radio. I originally thought this code would work

<RadioGroup
    onChange={this.updateSelectedOption}
>
    <Radio
        id="id1"
        label="label1"
        checked={this.state.selectedOption === OptionType.Option1}
    />
    <Radio
        id="id2"
        label="label2"
        checked={this.state.selectedOption === OptionType.Option2}
    />
</RadioGroup>

however, changing the state in RadioGroup's onChange did not update the selected Checkbox, and there was no documentation in storybook around this

I ultimately figured out that checked was not the controlling prop when used in RadioGroup and I needed to set RadioGroup's value

<RadioGroup
    onChange={this.updateSelectedOption}
    value={this.state.selectedOption === OptionType.Option1 ? 0 : 1}
>
    <Radio
        id="id1"
        label="label1"
    />
    <Radio
        id="id2"
        label="label2"
    />
</RadioGroup>

but this would have saved time and confusion if there was proper doc around these props. And also will help to distinguish which props may be used for accessibility vs functionality.

[lychyi]

As an update, we are currently working on developer experience as a whole so this will definitely get prioritized soon.

[NicholasBoll]

We are in the process of upgrading to Storybook 5.2 and are planning to inline prop documentation. This will essentially deprecate prop definitions in the Readme.md files so they are only documented inline. Storybook then extracts them out and adds to Storybook documentation, so this will become a normal practice.

[alanbsmith]

Closing this as Done. We now have prop documentation in our stories.