Add READMEs to all block-editor components

[youknowriad]

The Block Editor package in Gutenberg is full of components used to build blocks or block editors. These components lack documentation.

This issue is a tracking issue for the documentation effort to add READMEs to all these components.

If you want to help with this:

• Grab a component in the block-editor package that lacks a README
• Comment on the issue that you want to help document this component
• Write a README.md file for this component following the same format as the already documented components.

---

Updated by @t-hamano

If someone works on this issue, in addition to adding a README file, it would be great if we could also add JSDoc.
The block editor package reference is generated with a JSDoc reference for each component. Components that don't have JSDoc will look like this in the reference:

The recommended complete JSDoc format should look like this:

/**
 * Component description here.
 *
 * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/my-component/README.md
 *
 * @example
 * ```jsx
 * function MyComponent() {
 *   return (
 *     <MyComponent />
 *    );
 * }
 * ```
 *
 * @param {Object}  props        Component props.
 * @param {string}  props.prop1  props description here.
 * @param {Array}   props.prop2  props description here.
 * @return {Element} My component control.
 */
export default function MyComponent( {
	prop1,
	prop2,
} ) {
	return (
		<div>
			My Component
		</div>
	);
}

[alita-moore]

I want to make a README for the block-alignment-matrix-toolbar, issue #22516 ; How should I proceed? Is this a README for the issue or for the component?

[youknowriad]

@alita-moore yes, a README is needed for that component. so you should add a file to the component folder name it README.md, copy some existing component README to get the "base template" and fill it.

[alita-moore]

Okay,

This README

Doesn't have a very defined structure. Are you saying to copy the format in terms of linking to the parent directory?

[youknowriad]

Yes, this is not the best example. This might work better https://github.com/WordPress/gutenberg/blob/master/packages/components/src/button/README.md

[alita-moore]

Oh okay, that's much better.

Thank you for info, I'll get cracking 👩‍💻

[JustinyAhin]

Working on a pull for BlockBreadcrumb componenent https://github.com/WordPress/gutenberg/tree/master/packages/block-editor/src/components/block-breadcrumb

[JustinyAhin]

I've identified all the packages that haven't yet a README.

[t-hamano]

If someone works on this issue, in addition to adding a README file, it would be great if we could also add JSDoc.
The block editor package reference is generated with a JSDoc reference for each component. Components that don't have JSDoc will look like this in the reference:

The recommended complete JSDoc format should look like this:

/**
 * Component description here.
 *
 * @see https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/my-component/README.md
 *
 * @example
 * ```jsx
 * function MyComponent() {
 *   return (
 *     <MyComponent />
 *    );
 * }
 * ```
 *
 * @param {Object}  props        Component props.
 * @param {string}  props.prop1  props description here.
 * @param {Array}   props.prop2  props description here.
 * @return {Element} My component control.
 */
export default function MyComponent( {
	prop1,
	prop2,
} ) {
	return (
		<div>
			My Component
		</div>
	);
}

[0x8sksr]

Can guide me on how to start or just go with the example from the other documented components, such as this one for button? Thanks!

[t-hamano]

@0x8sksr There are many components in the block-editor directory that already have READMEs, so you can use those as a reference.