Try/jsdoc parser

[oandregal]

Playground to understand how to use jsdoc and jsdoc-parser to generate API documentation and how it relates to #13329

As per the instructions in the core ticket, in the Gutenberg root folder, execute:

npm run clean:packages # so any build/ build-module/ folders aren't detected by jsdoc
npm install
npx jsdoc -c jsdoc.conf

and open the generated file parsed-jsdoc.json (see here the raw formatted file).

Questions

Here's a set of questions I don't have answers for yet:

• How to restrict generated documentation to the Public API?
• How to document symbols that are exported but don't have a JSDoc comment?
• How to document functions exported as variables?
• How to document default exports?
• How to document renamed exports?
• How to document export chains?

How to restrict generated documentation to the Public API?

Example: packages/dom package.

Symbols that should be documented (and are):

• computeCaretRect
• documentHasSelection
• getOffsetParent
• getRectangleFromRange
• getScrollContainer
• insertAfter
• isEntirelySelected
• isHorizontalEdge
• isTextField
• isVerticalEdge
• placeCaretAtHorizontalEdge
• placeCaretAtVerticalEdge
• remove
• replace
• replaceTag
• unwrap
• wrap

Symbols that we shouldn't be documented (and are):

• isSelectionForward
• caretRangeFromPoint
• hiddenCaretRangeFromPoint
• isVisible (in focus.focusable)
• isValidFocusableArea (in focus.focusable)
• getTabIndex (in focus.tabbable)
• mapElementToObjectTabbable (in focus.tabbable)
• mapObjectTabbableToElement (in focus.tabbable)
• compareObjectTabbables (in focus.tabbable)

In this package, we should document the named export focus, but we don't. This is a tricky one. Here's what jsdoc finds and what not:

• focus
  • focusable
    • find: this is found by jsdoc but assigned the dom namespace, we should use dom.focus.focusable.find instead.
  • tabbable
    • isTabblableIndex: found by jsdoc but assigned the dom namespace, we should use dom.focus.focusable.find instead.
    • find: not reported because it doesn't contain any JSDoc comments.

How to document symbols that don't have a JSDoc comment?

In the above example, jsdoc didn't report the existence of focus.tabbable.find because it didn't have any JSDoc comment.

How to document functions exported as variables

• Example: packages/a11y package. We should have two functions documented (setup, speak) but they aren't.

This is a common pattern: export const myFunction = ( ... ) => { ... }?. It looks like jsdoc classifies this as a member and doesn't provide input/output information.

How to document default exports?

• Example: packages/api-fetch package. The default export isn't documented.

• Example: packages/components. It looks like jsdoc needs a @module tag to detect the default exports. That could solve the particular case of packages/api-fetch, but how would we document default exports in sub-folders?

How to document renamed exports?

• Example: packages/block-library. It should document a few functions children, node, serialize, parse exported through api.js that are renamed from the default export.

• Example: packages/components. Almost all components are exported in src/index.js by renaming the default exports.

• Example: packages/compose. Besides the renamed default exports, we also should report the compose named export that is renamed from flowRight.

How to document export chains?

• Example: packages/editor.

The editor exports a variety of things. We should document mediaUpload as a function in the wp.editor namespace. Because it's exported through a export chain it isn't properly reported by jsdoc (it is reported, but its name is "exports", it should be mediaUpload).

[herregroen]

On recognising functions:

1. Add the @function tag to the docblocks to explicitly declare the type.
2. In the template check if member nodes still have params and if so export them as functions.
3. Refactor to export function instead of export const.

Regarding default exports:
JSDoc's module detection seems to be reliant on the declaration of an @module tag at the top of the file so it knows what the default is and in which object the named exports are included.

Adding a comment including the @module wp.editor.components.colors at the top of index.js might see better results. It's also possible to explicitly name exports using either the @name tag or by adding an argument to the @function tag to declare something a function and explicitly name it at the same time.

I'm not sure what the above will do for functions that aren't exported. If they are still exported then it's likely they'll be in the global namespace. It would be possible to adapt the template to filter out any nodes in the global namespace except for a whitelist. Generally everything exported should be in the wp namespace.

[oandregal]

Closing for now. We are going to try a different approach. Context https://meta.trac.wordpress.org/ticket/3063#comment:9