Support for documenting component props in the component docBlock

まず、コンポーネントの docBlock、JSDoc タグ、propTypes プロパティコメントが現在どのように解釈されているかを確認します。foobar.foo のようなネストされた名前を含め、提案されている @prop 形式と @react.prop 形式を比較し、機能を実装してテストする前に、サポートする構文と生成されるドキュメントを定義します。

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?