Support for documenting component props in the component docBlock

[sigurdsvela]

As of now, the docblock describing a property must be directly above where the property field is defined. As such

class MyComponent {
    static propTypes = {
        /**
         * Does things that only a foo can
         */
        foo: PropTypes.string,

        /**
         * Does things that only a bar can
         */
        bar: PropTypes.string,
    }
}

Which is a fine solution, but can get very bloated when you start having more props.

class MyComponent {
    static propTypes = {
        /**
         * Does things that only a foo can
         */
        foo: PropTypes.string,

        /**
         * Does things that only a bar can
         */
        bar: PropTypes.string,

        /**
         * Does things that only a foobar can
         */
        foobar: PropTypes.shape({
            /**
             * Does things that only a foo can
             */
            foo: PropTypes.string,

            /**
             * Does things that only a bar can
             */
            bar: PropTypes.string,
        }),
        /**
         * Does things that only a foobar can
         */
        foobar: PropTypes.shape({
            /**
             * Does things that only a foo can
             */
            foo: PropTypes.string,

            /**
             * Does things that only a bar can
             */
            bar: PropTypes.string,
        }),
    }
}

You can online the comments, but with some descriptions being long enough to require being on two line, it ends up looking messy in my opinion.

class MyComponent {
    static propTypes = {
        /** Does things that only a foo can*/
        foo: PropTypes.string,

        /** Does things that only a bar can */
        bar: PropTypes.string,

        /** Does things that only a foobar can */
        foobar: PropTypes.shape({
            /**
             * Some properties will have a longer description that require them to be
             * on multiple lines
             */
            foo: PropTypes.string,

            /** Does things that only a bar can */
            bar: PropTypes.string,
        }),

        /** Does things that only a foobar can */
        foobar: PropTypes.shape({
            /** Does things only a foo can */
            foo: PropTypes.string,

            /** Does things that only a bar can */
            bar: PropTypes.string,
        }),
    }
}

What I'm proposing is a JSDoc like tag that allows you to descibe the props for a component in the docblock for the component itself, somthing like:

/**
 * @prop foo - Does things that only a foo can
 * @prop bar - Does things that only a bar can
 * @prop foobar - Does things that only a foobar can
 * @prop foobar.foo - Some properties will have a longer description that                         require them to be on multiple lines
 * @prop foobar.bar - Does things that only a bar can
 * @prop foobar - Does things that only a foobar can
 * @prop foobar.foo - Does things that only a foo can
 * @prop foobar.bar - Does things that only a bar can
 */
class MyComponent {
    static propTypes = {
        foo: PropTypes.string,
        bar: PropTypes.string,
        foobar: PropTypes.shape({
            foo: PropTypes.string,
            bar: PropTypes.string,
        }),
        foobar: PropTypes.shape({
            foo: PropTypes.string,
            bar: PropTypes.string,
        }),
    }
}

Seing as prop is an existing JSDoc tag, it might be an idea to prefix it with something. Perhaps react., so

/**
 * @react.prop name - description
 */

Is this something that would be worth looking into?

[rtsao]

If you're just using JSDoc syntax you might not need react-docgen and can use Babylon to extract comment blocks and parse them with https://github.com/eslint/doctrine directly

[sigurdsvela]

Mostly, I'm thinking that this would be a valuable feature for a react specific documentation tool, as the syntax is arguably cleaner in cases where you have 1 to 10-ish props(Which is the majority of components I run into).

Although, addressing your comment; I could have,
But I am very dependent on having the option to document props right above their declaration.

I would also like, in the future, to be able to 'deprecate' and give other meta data to specific props, which is much easier to define the syntax for if you allow for docblocks above the props declaration.
Which means that if I create something myself, I would probably have to reimplement a lot of what you guys have done here when that feature is needed.

[fkling]

This seems interesting. You could build your own handler (and publish it as an npm module) to enable such behavior.

I'm going to think about a bit more this week how we can make it easier to use custom handlers. I don't think it is sustainable in the long run to add more and more features to the core.

But something like this could definitely be a plugin.

[levithomason]

While is it slightly more concise in terms of line count, it does have some down sides. It requires duplicating prop names and keeping those in sync. It also moves the descriptions further away from the actual code. A plugin does make sense.

[davidlivingrooms]

@fkling That's really cool that you can supply your own custom handler! I haven't tried myself but I may give this a shot. I agree that the block comments are a little verbose in the majority of cases (at least for me). Most of the components I write tend to have a small number of props with single line comments. For example:

static propTypes = {
        foo: PropTypes.string, // Does things that only a foo can
        bar: PropTypes.string, // Does things that only a bar can
}

I like how this looks and it makes me feel good 😃. I understand that sometimes you may need a multi-line comment too though. It would be nice to have a custom handler that figures out what kind of comment you are using on a per prop basis. For example:

static propTypes = {
        foo: PropTypes.string, // Does things that only a foo can

        bar: PropTypes.string, // Does things that only a bar can

        /** Does things that only a foobar can */
        foobar: PropTypes.shape({
            /**
             * Some properties will have a longer description that require them to be
             * on multiple lines
             */
            foo: PropTypes.string,
            bar: PropTypes.string, // Does things that only a bar can 
        })
}

So, if there's a single line comment on the same line as the prop type declaration, use it. Otherwise, use the block comment above like normal.

In my opinion, the types of comments that can be detected should be as flexible as possible so more people can easily use react-docgen (since it is so awesome).

Thoughts? Do you guys think something like this would be possible through a custom handler?

[fkling]

@GrumpyPants, yes, if you look at this example (http://astexplorer.net/#/9vemjTFqdt) and select babel5 in the recast parser settings, you can see how to comment is attached to the property (it's in the comment property on the Property node), so it would absolutely possible to write a custom handler for that.