Support for documenting component props in the component docBlock

Bắt đầu bằng cách xem xét cách docBlock của component, các thẻ JSDoc và các comment thuộc tính propTypes hiện đang được diễn giải. So sánh các dạng @prop và @react.prop được đề xuất, bao gồm cả các tên lồng nhau như foobar.foo, đồng thời xác định cú pháp được hỗ trợ và tài liệu được tạo ra trước khi triển khai và kiểm thử tính năng.

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?