Support for documenting component props in the component docBlock

Start by reviewing how the component docBlock, JSDoc tags, and propTypes property comments are currently interpreted. Compare the proposed @prop and @react.prop forms, including nested names such as foobar.foo, and define the supported syntax and generated documentation before implementing and testing the feature.

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?