Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
juanmaguitar opened this issue Jul 29, 2024 · 1 comment
Open

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

juanmaguitar opened this issue Jul 29, 2024 · 1 comment
Labels
[Feature] Extensibility The ability to extend blocks or the editing experience [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.

Comments

@juanmaguitar
Copy link
Contributor

juanmaguitar commented Jul 29, 2024 •
edited
Loading

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
@priethor priethor added [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues. labels Jul 29, 2024
@ndiego ndiego added the [Feature] Extensibility The ability to extend blocks or the editing experience label Aug 12, 2024
@justintadlock justintadlock mentioned this issue Aug 27, 2024
Open
24 tasks
@vipul0425 vipul0425 mentioned this issue Jan 6, 2025
Open
@vipul0425
Copy link
Contributor

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 🙇

@Anuj-Rathore24 Anuj-Rathore24 mentioned this issue Jan 7, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
[Feature] Extensibility The ability to extend blocks or the editing experience [Type] Developer Documentation Documentation for developers [Type] Tracking Issue Tactical breakdown of efforts across the codebase and/or tied to Overview issues.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@juanmaguitar @ndiego @priethor @vipul0425