Repository navigation
Documentation: Add missing docs in editor package #60358
Description
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
- The documentation for editor package is auto generated, so after the addition of any JSDoc we need to
npm run docs:buildin order to update the README file. We shouldn't update manually the README file! - There are some linting rules for JSDoc. You can check this doc's section about setting this up in your code editor.
- 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 )
Activity
akasunil commentedon Apr 23, 2024
Looks like there is issue with
docs:buildcommand, It generate the documentation only if component is exported as default. Otherwise pipeline get failed. How do we resolve this ?ntsekouras commentedon Apr 23, 2024
@sunil25393 can you give me an example of this? Because I just tested with
usePostScheduleLabelwhich is not the default export and seems to work for me..akasunil commentedon Apr 23, 2024
Sure @ntsekouras, here is my draft PR #60932
colorful-tones commentedon May 8, 2024
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 commentedon May 20, 2024
We did not make it as far as I thought in our internal Contributor Day, but that is to be expected. I plan on still pursuing chipping away at the items. The biggest hurdle for many folks was the issue with
wp-scriptscommand failing: #61748I've since been running ESLint 10.0.2 locally and everything has been working smoothly. Perhaps @akasunil will continue pitching in as well. No worries if not. I just wanted to post an update. Thanks to @ntsekouras for continuing to chip away at code reviews 👏
ntsekouras commentedon May 21, 2024
Thanks so much for all the contributions from everyone and especially the initiative of @colorful-tones and the organized contributors day! 🚀
colorful-tones commentedon May 29, 2024
@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 commentedon May 30, 2024
@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 commentedon May 30, 2024
That sounds good, thank you!
Yeah, it would be great to do them all at once, since the changes would be minimal.
colorful-tones commentedon Jun 6, 2024
@ntsekouras it seems that
ServerSideRenderis 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
ntsekouras commentedon Jun 7, 2024
You're right. I'll remove it.
akasunil commentedon Jun 10, 2024
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'tfor 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 commentedon Jun 14, 2024
@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 commentedon Jun 14, 2024
@ntsekouras I'm not clear as to whether we need to add docs for
transformStyles, as it is inpackages/editor/src/index.js? 🤔https://github.com/WordPress/gutenberg/blob/trunk/packages/editor/src/index.js#L16
akasunil commentedon Jun 16, 2024
Sounds good. And we will mention this issue in a new issue for future reference.
ntsekouras commentedon Jun 20, 2024
Thank you all for the awesome work you did here! 🚀 Additional kudos to @colorful-tones for also organising a contributors day event!!
transformStylesis just for back compat, so we can skip it and close this issue.akasunil commentedon Jun 21, 2024
@colorful-tones I have created issue #62744 as we discussed