addon-docs: Descriptions per Story

Is your feature request related to a problem? Please describe.

According to the documentation there is currently one Description section on a DocsPage. This section is filled by the JSDoc comment /** */ used by my specified component. That’s awesome. I can place a general description here. (E.g. describe what my component <Button />.)

After that I have more specific stories showcasing different usages of a certain component. (E.g. showcasing <Button mode="primary" /> and <Button mode="secondary" />.)

It would be lovely if I could add a JSDoc comment to my stories so they show up on the DocsPage. E.g. something like that:

import React from 'react';
import { Button } from '../../src/components/button';

export default { title: 'Components|Button', component: Button };

export const All = () => (
  <>
    <Button mode="primary">Click me!</Button>
    {' '}
    <Button mode="secondary">Click me!</Button>
  </>
);

/**
 * Only use me once per page for the preferred user action.
 */
export const Primary = () => <Button mode="primary">Click me!</Button>;

/**
 * You can use me several times on a page for neutral actions.
 */
export const Secondary = () => <Button mode="secondary">Click me!</Button>;

Describe the solution you’d like

Everything could than be rendered like this:

Describe alternatives you’ve considered

I could use MDX files for this, but they currently lack any type checking which I’d like to keep (and I don’t really want to separate every example out of the MDX file into their own files, because I don’t know if this messes with things like the Source Loader for code examples 🤔). Also it’s a little bit easier to migrate to for existing Storybooks instead of rewriting everything to MDX.

Are you able to assist bring the feature to reality?

Probably, I can if I find a little bit of time.

---

IssueHunt Summary

shilman has been rewarded.

Backers (Total: $100.00)

• kylemh ($100.00)

Submitted pull Requests

• #19684 CSF-tools: Turn story comments into docs descriptions

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

[izhan]

Hey folks – long-time watcher of this thread here! I ended up creating a trivial Webpack loader a while back that got the job done. I only now had some extra time to put it on Github, which you can find here.

Code

// A `primary` button is used for emphasis.
export const Primary = () => <Button primary>Submit</Button>

/**
 * Use the `loading` prop to indicate progress. Typically use
 * this to provide feedback when triggering asynchronous actions.
 */
export const Loading = () => <Button loading>Loading</Button>

Output

Definitely not perfect and a bit specific to my codebase’s current setup, hence some quirks here and there. But figured I’d send it out in case anyone was looking for a starting point.

Also happy to improve on it more, but looks like there’s bigger, better plans brewing in this thread. Eager to help there too 😃

[issuehunt-app[bot]]

@kylemh has funded $100.00 to this issue.

---

• Submit pull request via IssueHunt to receive this reward.
• Want to contribute? Chip in to this issue via IssueHunt.
• Checkout the IssueHunt Issue Explorer to see more funded issues.
• Need help from developers? Add your repository on IssueHunt to raise funds.