Documentation: Add missing docs in editor package

[ntsekouras]

Recently, we added auto-generated docs for the editor package.

There are lots of undocumented APIs, so let's add what's missing.

• AutosaveMonitor #60882, #60905
• CharacterCount #60906
• DocumentBar #61733
• DocumentOutline #61129
• DocumentOutlineCheck #61129
• EditorHistoryRedo #60932
• EditorHistoryUndo #60932
• EditorKeyboardShortcuts #60933
• EditorKeyboardShortcutsRegister #60933
• EditorNotices #61736
• EditorProvider #61739
• EditorSnackbars #61110
• EntitiesSavedStates #62377
• ErrorBoundary #61950
• LocalAutosaveMonitor #61951
• PageAttributesCheck #60977
• PageAttributesOrder #60977
• PageAttributesPanel #60977
• PageAttributesParent #60977
• PageTemplate #61961
• PostAuthor #61090
• PostAuthorCheck #61090
• PostAuthorPanel #61090
• PostComments #61964
• PostDiscussionPanel #61966
• PostExcerpt
• PostExcerptCheck #60864
• PostExcerptPanel #61967
• PostFeaturedImage #61165
• PostFeaturedImageCheck #61165
• PostFeaturedImagePanel #61165
• PostFormat #61732
• PostFormatCheck #61732
• PostLastRevision #61166
• PostLastRevisionCheck #61166
• PostLastRevisionPanel #61166
• PostLockedModal #61968
• PostPendingStatus #61970
• PostPendingStatusCheck #61970
• PostPingbacks #62035
• PostPreviewButton #62036
• PostPublishButton #62379
• PostPublishButtonLabel #62379
• PostPublishPanel #62380
• PostSchedule #61345
• PostScheduleCheck #61345
• PostScheduleLabel #61345
• PostSchedulePanel #61345
• PostSlug #62102
• PostSlugCheck #62102
• PostSticky #62100
• PostStickyCheck #62100
• PostSwitchToDraftButton #62381
• PostSyncStatus #62382
• PostTaxonomies #62384
• PostTaxonomiesCheck #62384
• PostTaxonomiesFlatTermSelector #62384
• PostTaxonomiesPanel #62384
• PostTemplatePanel #61961
• PostTextEditor #62099
• PostTitle #61740
• PostTitleRaw #61740
• PostTrash #62116
• PostTrashCheck #62116
• PostURL #61737
• PostURLCheck #61737
• PostURLLabel #61737
• PostURLPanel #61737
• PostVisibility #61735
• PostVisibilityCheck #61735
• PostVisibilityLabel #61735
• TableOfContents #62385
• TextEditorGlobalKeyboardShortcuts #62116
• ThemeSupportCheck #62387
• TimeToRead #62116
• transformStyles
• useEntitiesSavedStatesIsDirty #62388
• usePostScheduleLabel #61345
• usePostURLLabel #61737
• usePostVisibilityLabel
• VisualEditorGlobalKeyboardShortcuts
• WordCount #62217

We can do this iteratively, but it would be probably best to do it in chunks.

Instructions

1. The documentation for editor package is auto generated, so after the addition of any JSDoc we need to npm run docs:build in order to update the README file. We shouldn't update manually the README file!
2. There are some linting rules for JSDoc. You can check this doc's section about setting this up in your code editor.
3. The generation script searches for JSDocs above the exported module. In some cases we declare the module, but export it in a different place (usually somewhere below in the same file). In that case we should add the JSDocs above the export.

Example:

function EditorHistoryRedo() { ... }
....
....

{ Add JSDoc here!!! } 
export default forwardRef( EditorHistoryRedo )

[akasunil]

Looks like there is issue with docs:build command, It generate the documentation only if component is exported as default. Otherwise pipeline get failed. How do we resolve this ?

[ntsekouras]

@sunil25393 can you give me an example of this? Because I just tested with usePostScheduleLabel which is not the default export and seems to work for me..

[akasunil]

Sure @ntsekouras, here is my draft PR #60932

[colorful-tones]

I'm just dropping an update here. I'm organizing an internal WP Engine Contributor Day on Thursday, May 16, 2024, and I plan on utilizing this issue to provide some folks with some quick wins and empower them to feel successful in their contribution efforts. Hopefully, we'll have all the items wrapped up that day. Thanks!

[colorful-tones]

@ntsekouras I'm happy to do a follow-up pull request to take a pass at refining the consistency of some of these docs. Two items I'm currently seeing:

Different use of @return (random sampling)

• @return {JSX.Element} The rendered dropdown content.
• @return {Component} The component to be rendered.
• @return {JSX.Element|null} The rendered button component.
• @return {Component|null} The component to be rendered. Return null if the post type doesn't...
• @return {Element} The component to be rendered.

Description phrasing (random sampling)

• Renders a control for enabling or disabling pingbacks and trackbacks in a WordPress post.
• Renders the PostSlug component. It provide a control for editing the post slug.
• This component renders a navigation bar at the top of the editor. It displays the title of the current...
• Component handles the keyboard shortcuts for the editor.

[akasunil]

@colorful-tones I had the same thinking; I was waiting for the remaining documents to be completed so that we could refine them all at once.

[ntsekouras]

I'm happy to do a follow-up pull request to take a pass at refining the consistency of some of these docs. Two items I'm currently seeing:

That sounds good, thank you!

I was waiting for the remaining documents to be completed so that we could refine them all at once.

Yeah, it would be great to do them all at once, since the changes would be minimal.

[colorful-tones]

@ntsekouras it seems that ServerSideRender is deprecated and should not be on the list, correct? I just wanted to verify. Thanks.

gutenberg/packages/editor/src/components/deprecated.js

Line 62 in 247369b

export { default as ServerSideRender } from '@wordpress/server-side-render';

[ntsekouras]

@ntsekouras it seems that ServerSideRender is deprecated and should not be on the list, correct? I just wanted to verify

You're right. I'll remove it.

[akasunil]

I would go with these options for documentation uniformity

for return of component,
@return {Component|null} The component to be rendered or null if the post type doesn't

for description of component,
Renders a control for enabling or disabling pingbacks and trackbacks in a WordPress post.
Following simple structure of Render { render what? } for { whats the use } makes it easy to understand the purpose of component.

@colorful-tones @ntsekouras Let me know your thoughts.

[colorful-tones]

@akasunil I think your suggestions make sense.

I recommend we finalize the initial work in this issue, close it and then open a follow-up issue with notes/reference back to this one and submit a separate pull request towards the newer issue. Reasoning: clean break for work and intent, but I'm open to other ideas. Perhaps that is more work. 🤷

[colorful-tones]

@ntsekouras I'm not clear as to whether we need to add docs for transformStyles, as it is in packages/editor/src/index.js? 🤔

https://github.com/WordPress/gutenberg/blob/trunk/packages/editor/src/index.js#L16

[akasunil]

recommend we finalize the initial work in this issue, close it and then open a follow-up issue with notes/reference back to this one and submit a separate pull request towards the newer issue.

Sounds good. And we will mention this issue in a new issue for future reference.

[ntsekouras]

Thank you all for the awesome work you did here! 🚀 Additional kudos to @colorful-tones for also organising a contributors day event!! transformStyles is just for back compat, so we can skip it and close this issue.

[akasunil]

@colorful-tones I have created issue #62744 as we discussed