rich-text: set up autogenerated API docs

[oandregal]

Related to #14227

This PR sets up auto-generated API docs for the rich-text package through the npm run docs:build command and updates its README file.

Notable modifications

• Fixed optional parameters. Should be {type} [param], not {?type} param.
• Fixed returns when type can be undefined. Should be {type|undefined}, not {?type}.
• New symbols added that were undocumented:
  • insertObject
  • unregisterFormatType
• Symbols that were documented and are removed in this PR: apply.
• Symbols that stay undocumented:
  • changeListType
  • charAt
  • getSelectionEnd
  • getSelectionStart
  • indentListItems
  • insertLineBreak
  • insertLineSeparator
  • isEmptyLine
  • LINE_SEPARATOR
  • outdentListItems
  • unstableToDom

Test instructions

• Delete or modify the contents at packages/rich-text/README.md within the start <!-- START TOKEN(Autogenerated API docs) --> and end <!-- END TOKEN(Autogenerated API docs) --> tokens.
• Execute npm run docs:build and verify they are re-created.
• Review that the API docs match the JSDoc of the exported symbols.

[ellatrix]

Thanks! I would rather not document any functions that are currently not documented in master. I guess either we should remove the functions or mark them as unstable (e.g. all the list specific functions).

[gziolo]

I guess either we should remove the functions or mark them as unstable (e.g. all the list specific functions).

Ideally, we fix export statement and JSDocs so the tool could do its job :)

[ellatrix]

Ideally, we fix export statement and JSDocs so the tool could do its job :)

It would ignore function names prefixed with unstable right?

[oandregal]

@ellatrix Added apply and changeListType to the list of symbols to be ignored. Let me know if there are more we should ignore.

Although this works it makes me think about how apply and changeListType can communicate they are for internal use only while not having a unstable/experimental/etc prefix. One thing we can do is to add the @private JSDoc tag. Thoughts?

Although the auto-documentation tool doesn't currently ignore the exported symbols that contain a @private tag, we could easily add support for it. It'll be useful for other things as well, for example, to avoid documenting symbols that are exported for testing purposes.

[chrisvanpatten]

@nosolosw I really like the idea of supporting @private. Feels very appropriate.

[nerrad]

One thing we can do is to add the @private JSDoc tag. Thoughts?

Big ➕from me on this.

However, I still think it's important that any publicly accessible api (regardless of whether its documented or not) that is not considered "final" should be prefixed with __experimental/ __unstable. I think the prefix on the actual functions communicates a bit more clearer than @private would. Plus @private, might be something we'll use for apis that we don't document but are still considered "final" for internal use.

So, I do think adding this tag would be a great complement to what we already do with prefixes. It would certainly make it easier for the auto doc generator to know what to skip.

[chrisvanpatten]

@nerrad wish I could give you a bigger 👍 on that. Agree completely!

[oandregal]

@ellatrix I missed tons of spaces! Sorry about that.

Initially, I updated the JSDoc comments with info that was on the current README docs but wasn't present in the JSDoc comment. Having to deal with a myriad of packages at #14227 I didn't know better.

However, I ended up doing a full audit of these API docs. I added the notable modifications this PR introduces in the description. Would you mind taking a look at that to see if it makes sense to you?

The only change that stands out to me as potentially wrong is the suggestion to remove apply from the docs. If it was already documented should we keep it that way (I'm unfamiliar with how we proceed with this kind of thing)?

[ellatrix]

Looks great, thanks!