Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Addon docs: Display @deprecated props #9721

Open
ricovitch opened this issue Feb 3, 2020 · 18 comments
Open

Addon docs: Display @deprecated props #9721

ricovitch opened this issue Feb 3, 2020 · 18 comments

Comments

@ricovitch
Copy link

ricovitch commented Feb 3, 2020

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
Screenshot 2020-02-03 at 12 14 17

@shilman
Copy link
Member

shilman commented Feb 3, 2020

Great feature @ricovitch!!! cc @patricklafrance

@patricklafrance
Copy link
Member

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

@domyen
Copy link
Member

domyen commented Feb 10, 2020 via email

@patricklafrance
Copy link
Member

@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
Copy link
Member

domyen commented Feb 12, 2020

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.

image
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.

image

What do y'all think?

@patricklafrance
Copy link
Member

@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
Copy link
Author

ricovitch commented Feb 12, 2020

@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
Copy link
Member

shilman commented Feb 12, 2020

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
Copy link
Member

domyen commented Feb 13, 2020

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 added a commit that referenced this issue Feb 14, 2020
@shilman
Copy link
Member

shilman commented Feb 14, 2020

Repro: 94a8ae7

@menosprezzi
Copy link

Hello guys!
Any updates?

@domyen
Copy link
Member

domyen commented Dec 4, 2020 via email

@vdavyskiba
Copy link

vdavyskiba commented Jan 27, 2022

I have another workaround using compodoc json:

import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';

const fixCompodocJson = doc => ({
  ...doc,
  components: doc.components.map(component => ({
    ...component,
    propertiesClass: component.propertiesClass.map(prop => ({
      ...prop,
      rawdescription: prop.deprecated ? `\n\n **deprecated**: ${prop.deprecationMessage} ${prop.rawdescription}\n` : prop.rawdescription
    }))
  }))
});

setCompodocJson(fixCompodocJson(docJson));

It allows usage @deprecated annotation:

  /**
   * This is my control
   * @deprecated This field is deprecated
   */
  myControl = new FormControl();

yen-tt added a commit to yext/search-ui-react that referenced this issue Nov 17, 2022
this pr mark LocationBias as deprecated in favor of the new Geolocation component.

I checked if storybook have some feature to inform user that a component is deprecated, there's an open feature request: storybookjs/storybook#9721 for displaying @deprecated props but nothing official yet. I did come across a custom addon: https://storybook.js.org/addons/@etchteam/storybook-addon-status which seems to work quite nicely.

Show "Deprecated" status for location bias stories:
<img width="782" alt="Screen Shot 2022-11-16 at 4 31 20 PM" src="https://user-images.githubusercontent.com/36055303/202298691-49bd8a5a-9332-4f93-8f42-0a7c408ae052.png">

J=SLAP-2448
TEST=none
@Seminioni
Copy link

Anything new on the issue? What's the best way to implement @deprecated feature in storybook?

@WalterWeidner
Copy link

WalterWeidner commented Jan 13, 2023

We are also interested in this so that we don't need to add an additional note elsewhere for deprecated props. I'd be happy to throw something together if someone can point me to the right area of the code (kind of dizzying navigating between the packages).

@anambl
Copy link

anambl commented Apr 12, 2023

Hello! Are there any updates on this? Would be amazing to have this as the current deprecated message is easy to miss. The experimental tag would be very useful too, it's currently not supported at all 😞

@shilman shilman removed the todo label Jun 20, 2023
@ricovitch
Copy link
Author

For anyone interested, we currently manage deprecated props by using a specific jsdoc description

/** **Deprecated:** use `variant` */
contained?: boolean;

Also we declare deprecated props separately from supported props, so that argstable display them at the end of the table.

export type ButtonProps = Props &
  DeprecatedProps &
  Omit<ButtonHTMLAttributes<HTMLButtonElement>, keyof Props & DeprecatedProps>;

Screenshot 2023-08-07 at 18 13 18

I would love the possibility to display a badge in addition to the description, to make it more obvious.

@KevinGhadyani-Okta
Copy link

KevinGhadyani-Okta commented Nov 1, 2023

I'm using the argTypes syntax because my Storybook is in a separate monorepo package than the code.

Even still, I can't get the automatic deprecation working with the comment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

10 participants