Add documentation for object key in registerFormatType settings

[fabiankaegy]

The registerFormatType function from the @wordpress/rich-text package takes a settings object as the second parameter. This settings object is typed as WPFormat here in the code:

gutenberg/packages/rich-text/src/register-format-type.js

Lines 9 to 20 in a7e2895

	/**
	* @typedef {Object} WPFormat
	*
	* @property {string} name A string identifying the format. Must be
	* unique across all registered formats.
	* @property {string} tagName The HTML tag this format will wrap the
	* selection with.
	* @property {string} [className] A class to match the format.
	* @property {string} title Name of the format.
	* @property {Function} edit Should return a component for the user to
	* interact with the new registered format.
	*/

however there are also other none documented settings that are being used in the Gutenberg codebase like the object key used in the core/image format:

gutenberg/packages/format-library/src/image/index.js

Line 24 in 60827ac

object: true,

It would be great to get some documentation added for this undocumented key.

[fabiankaegy]

From what I can tell the object key is there indicating that the tagName is self-closing and therefore doesn't need a closing tag added. But that is only a very uneducated guess based on what it seems to be doing in the core/image format.

[github-actions]

Hi,
This issue has gone 180 days without any activity. This means it is time for a check-in to make sure it is still relevant. If you are still experiencing this issue with the latest versions, you can help the project by responding to confirm the problem and by providing any updated reproduction steps.
Thanks for helping out.

[codebykat]

Ran into this issue this week :)

Starting from the Format API tutorial here: https://developer.wordpress.org/block-editor/how-to-guides/format-api/ you can get to https://developer.wordpress.org/block-editor/reference-guides/packages/packages-rich-text/#registerformattype which tells you about WPFormat as a type, but that type is not defined anywhere.

In general the format API is missing a lot of documentation. e.g. I also needed to know what parameters the edit function will receive; it turns out it can get activeAttributes and that toggleFormat can have an attributes parameter in its Format argument as well, which can be used to pass styles.

[fabiankaegy]

@ellatrix Do you maybe have some insight here? :) Would love to update the documentation to reflect all the options

[mburridge]

@fabiankaegy, @codebykat what can we do to get this resolved. Happy to help with a PR if you give me some hints/guidance.

[fabiankaegy]

@mburridge im on the same page as you. I would have submitted a PR long ago if I fully understood what the object key is for.

I was hoping to get some input from someone more familiar with the code here so that we can then document it.

From my understanding objects are elements that are self closing like for example image tags. Whilst other elements that wrap content are no objects.

[mburridge]

@gziolo I know it was about four years ago that you did this, but pinging you in case you're able to help with this. Can you explain what the WPFormat object is here? Also is this list complete and up-to-date, or have there been developments that mean this list needs to be added to?

[gziolo]

Looking at the code I see WPFormat describes the settings that you pass when registering a new format type which is then exposed in the UI when editing RichText fields.

I don't have the knowledge necessary to tell whether this type definition is up to date.

[youknowriad]

I might suggest to try to type this package file per file until it's fully typed (which gives us the documentation for free)