Storybook: Addon-docs: Support JSDoc params to describe the signature of a function in the props table

[patricklafrance]

Is your feature request related to a problem? Please describe.
I would like to be able to define the signature of my function in description column of the props table.

I love how it's done in Semantic UI React documentation

This is define with JSDoc:

    /**
     * Called on blur.
     *
     * @param {SyntheticEvent} event - React's original SyntheticEvent.
     * @param {object} data - All props.
     */
    onBlur: PropTypes.func,

This doesn't seem to be a native feature of react-docgen. I made a quick test on the playground and I get the following:

    "bar": {
      "type": {
        "name": "custom",
        "raw": "function(props, propName, componentName) {\n  // ...\n}"
      },
      "required": false,
      "description": "Description of prop \"bar\" (a custom validation function).\n@param {SyntheticEvent} event - Test",
      "defaultValue": {
        "value": "21",
        "computed": false
      }
    },

I guess they somehow parse the JSDoc in the description prop.

[patricklafrance]

Any tips on how to implement this @layershifter ?

[layershifter]

@patricklafrance we have there the additional processing of results from react-docgen to get more descriptive types. We also parse JSDoc with doctrine (it's deprecated, BTW, sic!) to parse tags: https://github.com/Semantic-Org/Semantic-UI-React/blob/master/gulp/plugins/util/parseDocblock.js

[anwalkers]

@layershifter Take a look at the Typedoc project for inspiration. They have done great work generating static docs.

https://typedoc.org/

[patricklafrance]

Thank you very much @layershifter !

[patricklafrance]

It could be done in a lot of ways, here's 2 options:

Render the function signature in the description column.

This is similar to the screenshot above.

The main advantage of this implementation is space:

+

• The function parameters description can be rendered
• Most of the time, the signature will fit on a single line

-

• It might be counter intuitive to have the function signature in the description column instead of the type column.

Render the function signature in the type column.

+

• Intuitive

-

• Currently the type column doesn't take much space since most of type names are short. A function signature tends to be quite wide. Most of the time, the type column will either get very large or truncate the function signature on multiple lines.
• The function parameters description cannot be rendered

What do you think @shilman ?

[shilman]

@patricklafrance Currently, the prop type is rendered in the Description column, which indeed is more compact. I think we should keep it that way, since the full design (which is not yet implemented) also has a "knob" column to edit the prop value, and it starts to get crowded as we add more columns.

@domyen this is your design -- anything to add?

[patricklafrance]

That make sense!

[domyen]

Description column makes sense to me. We can make further layout
optimizations when more people start using it.

On Sun, Oct 27, 2019 at 11:03 PM Patrick Lafrance [e-mail]
wrote:

That make sense!

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/storybookjs/storybook/issues/8532?email_source=notifications&email_token=AACAJWMYOGRDVI6ACGLBRBDQQZI75A5CNFSM4JEBKVP2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECLRQ5A#issuecomment-546773108,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AACAJWKEDZ5TJ63NDT3NBTLQQZI75ANCNFSM4JEBKVPQ
.

[shilman]

Ooh-la-la!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.3.0-alpha.36 containing PR #8660 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.

[patricklafrance]

Still need to add the @params and @returns tags optional description under the func type.

Working on it now!

[shilman]

w00t!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.3.0-alpha.41 containing PR #8702 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

Closing this issue. Please re-open if you think there's still more to do.

[Losses]

@shilman This feature is not work with the combination of TypeScript + React + tsdocs, any idea about this?

[shilman]

@Losses there are two different codepaths, one for react-docgen-typescript-loader (the recommended 5.3 setup) and one for babel-plugin-react-docgen (the recommended 6.0 setup). i'm guessing @patricklafrance fixed this for the former but not the latter.

More info: https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#rolling-back

[Losses]

@shilman I should open a new issue or just reopen this issue?

[shilman]

Related: #10311

[Losses]

Related: #10311

Cool!