Storybook: Addon docs: Display @deprecated props

[ricovitch]

For library maintainers using storybook docs to document components props, it's very useful to be able to document deprecated props.

We just migrated from styleguidist to storybook and this was nicely managed with styleguidist by parsing "@deprecated" jsdoc comments.
Corresponding prop would then be displayed striked through, and bold, making it easy to visualize for end users.

Describe the solution you'd like
Please parse "@deprecated" jsdoc comments and add styles in Props table for them

Describe alternatives you've considered
For now we have filtered deprecated props in the tsDocgenLoaderOptions / propFilter config.
So we do not display them, but that's a temporary solution.

EDIT : We replaced js doc "@deprecated" comments with something like this as a workaround

/**
 * **Deprecated:** Use otherPropName
 */

Are you able to assist bring the feature to reality?
I would like to help, but i really don't know where to start.

Additional context
Styleguidist deprecated props display

[shilman]

Great feature @ricovitch!!! cc @patricklafrance

[patricklafrance]

@domyen if you can provide some guidance for the UI I can add support for deprecated in 6.0

[domyen]

That’s awesome! Can you tell me more. Is this the use case of a component
api (props) changing and the component author wanting to mark it as
deprecated?

On Fri, Feb 7, 2020 at 12:28 PM Patrick Lafrance [e-mail]
wrote:

@domyen https://github.com/domyen if you can provide some guidance for
the UI I can add support for deprecated in 6.0

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

[patricklafrance]

@domyen yes this is exactly what it is.

Here's how it could be use:

    /**
     * The width of the button
     *
     * @deprecated Do not use! Use `size` instead!
     */
    width: PropTypes.number,

[domyen]

Thanks for the context @patricklafrance and @ricovitch.

Styleguidist has a pleasant deprecated experience! That's a good starting point for us.

Strawman design with a few adjustments.

• Move deprecated props to the bottom of the table. When a prop is deprecated and replaced, we want to discourage component consumers from being exposed to props they shouldn't use.
• Use a yellow warning badge for "Deprecated" to make it evident that the prop should not be used.

API
The way this _could_ work is to scan for @deprecated in the JS/TSdoc comments for props. If it exists anywhere in the comment show a badge. Otherwise render the comment as normal.

For instance this would render everything the comment as normal but omit @deprecated string.

    /**
     * The width of the button
     *
     * @deprecated Do not use! Use `size` instead!
     */
    width: PropTypes.number,

In practice, the way I'd use this myself in Storybook's Design System is to start with the badge.

    /**
     * @deprecated Do not use! Use `size` instead! 
     * The width of the button
     */
    width: PropTypes.number,

It's also common for component libraries to have other badges like "Experimental" and "Undocumented". We could use the same technique to show them as well.

What do y'all think?

[patricklafrance]

@domyen thanks! I like the idea of moving the props at the end of the table and using badges for “deprecated” and “experimental”.

My only concerns here is about the deprecation message. I feel like there should be more emphasis on it since it’s not near the badge. What do you think?

[ricovitch]

@domyen love the idea of the @deprecated and @experimental badges. I also agree with @patricklafrance about the emphasis on the message. Would it be possible to put the badges near the message ?

I'm asking myself about usefulness of leaving the original message if it's deprecated.
The only info the end user wants to know about a deprecated prop is what to use instead isn't it ?
It makes it also more easy to scan i think.
But that's my point of view, in the end it should be the author decision to leave a message additionally to the deprecated info. I just feel like it's two different things : the deprecated / migration info, and the prop description.
And i d'like the deprecated info to be displayed near the badge i think.

[shilman]

I like @domyen's layout since it makes good use of space. We could lighten the original usage message, type, and default value to subdue them, so they are still available but the deprecation method is the focus.

[domyen]

Thanks for the feedback everyone. The intended behavior here is to extract @deprecated and @experimental to showcase them as badges. In addition, strike through the deprecated prop name.

I don't think we need to do anything to the description. It's easier to implement and leaves the control in the authors hands. If they want to replace the message with alternate instructions they should do that via a regular comment.

[shilman]

Repro: https://github.com/storybookjs/storybook/commit/94a8ae7a3b22919a41a102521e0b1e9611b977f0

[menosprezzi]

Hello guys!
Any updates?

[domyen]

I don’t think this has been built yet. Would be open to a PR from folks in
the community.

On Fri, Dec 4, 2020 at 3:20 PM Guilherme Prezzi [e-mail]
wrote:

>
>

Hello guys!

Any updates?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/storybookjs/storybook/issues/9721#issuecomment-738998469,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AACAJWIPIRSNVJVMLVHE5YDSTFACBANCNFSM4KPDLQ3A
.