Docs: Add explanations about attributes of each Core Block in the documentation (and in the source code)

[juanmaguitar]

The only official documentation available for core blocks is located at Block Editor Handbook > Reference Guides > Core Blocks Reference. This page lacks detailed explanations about each core block’s attributes and points the user to the source code for more information.

Providing extra explanations about the attributes of core blocks is essential for developers to fully understand and utilize these blocks effectively.

I propose including JSDoc comments in the Edit component of each block to explain the props.attributes object received by every core block’s edit component.

Besides providing extra info on these attributes directly in the source code, these descriptions could also be used (with some custom extra code) by gen-block-lib-list.js to generate more extended info for each block at Block Editor Handbook > Reference Guides > Core Blocks Reference

• archives
• audio
• avatar
• block
• block-keyboard-shortcuts
• button
• buttons
• calendar
• categories
• classic.scss
• code
• column
• columns
• comment-author-avatar
• comment-author-name
• comment-content
• comment-date
• comment-edit-link
• comment-reply-link
• comment-template
• comments
• comments-pagination
• comments-pagination-next
• comments-pagination-numbers
• comments-pagination-previous
• comments-title
• common.scss
• cover
• details
• editor-elements.scss
• editor.scss
• elements.scss
• embed
• file
• footnotes
• form
• form-input
• form-submission-notification
• form-submit-button
• freeform
• gallery
• group
• heading
• home-link
• html
• image
• latest-comments
• latest-posts
• list
• list-item
• lock-unlock.js
• loginout
• media-text
• missing
• more
• navigation
• navigation-link
• navigation-submenu
• nextpage
• page-list
• page-list-item
• paragraph
• pattern
• post-author
• post-author-biography
• post-author-name
• post-comment
• post-comments-count
• post-comments-form
• post-comments-link
• post-content
• post-date
• post-excerpt
• post-featured-image
• post-navigation-link
• post-template
• post-terms
• post-time-to-read
• post-title
• preformatted
• pullquote
• query
• query-no-results
• query-pagination
• query-pagination-next
• query-pagination-numbers
• query-pagination-previous
• query-title
• quote
• read-more
• rss
• search
• separator
• shortcode
• site-logo
• site-tagline
• site-title
• social-link
• social-links
• spacer
• table
• table-of-contents
• tag-cloud
• template-part
• term-description
• text-columns
• verse
• video

[vipul0425]

Hi @juanmaguitar,

I’ve created an initial PR for this issue (#68508). It includes the additional code changes to the gen-block-lib-list.js script and adds the documentation comment for the archives block.
For the JSDoc comment, I referred to the guidance shared here: #22891 (comment), as mentioned by @t-hamano.

Looking forward to your feedback.
Thanks 🙇

[stokesman]

I agree with the idea here. My initial thought on the proposal of adding JSDoc comments to the Edit components is that it introduces duplication and therefore seems less than ideal for maintenance.

Has adding this directly in block json been considered? There each attribute already supports some relevant metadata (type and default). What about adding a description for attributes? I can think of two ways that might be done. Either adding it as a property or supporting JSON5 and adding it as a comment.

Adding a description property to attributes seems the simpler idea. However, ideally their data wouldn’t contribute to any bundle size increases and for that it seems a custom JSON loader for Webpack that could strip such properties would be wanted. Additionally—though likely of lesser concern—the generation of blocks-json.php in core might also strip the properties.

Supporting JSON5 would probably be more work yet would seemingly have a broader appeal. Adding attribute descriptions in the way of comments should avoid the concern of bundle size increases. However, that might be less simple with regards to generating docs.

[Mamaduka]

Putting this proposal on hold until the following items are considered/resolved:

• Standardized way of documenting block attributes. I agree with @stokesman that JSDoc comments might not be the best option.
• A parser that can include these details in documentation. There's already one parsing block attribute name from the block.json file; it might be easier to reuse that.

tl;dr, we need to have a good plan before moving forward and updating dozens of files.

cc @vipul0425, @Anuj-Rathore24, @dhruvikpatel18

[t-hamano]

If we wanted to use JSON5 or JSONC to be able to insert comments, we'd probably have to convert all block.json to block.json5 or block.jsonc, and the @wordpress/scripts would have to support the new extensions, right?

On the other hand, because additionalProperties is not defined in the attributes field, any field can be added, so it would be possible to add a field such as description. However, ideally additional fields should not be allowed.

[Mamaduka]

IIRC, JSON5 or JSONC aren't supported by default in PHP, so I doubt the format change.

P.S. There was a similar conversation for the theme.json format change, and I remember that was one of the reasons.