Support for documenting component props in the component docBlock

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?

Commencez par examiner comment les commentaires de composant docBlock, les balises JSDoc et les commentaires de propriétés propTypes sont actuellement interprétés. Comparez les formes proposées @prop et @react.prop, y compris les noms imbriqués tels que foobar.foo, et définissez la syntaxe prise en charge ainsi que la documentation générée avant d’implémenter et de tester la fonctionnalité.