Show JavaScript documentation on developer.wordpress.org

[atimmer]

There is a ton of work going into making the JavaScript documentation up to the same standard as the PHP documentation. This is now in a state where we could feasibly add it to developer.wordpress.org.

After ​https://core.trac.wordpress.org/ticket/41682#comment:7 has been merged the output is useful.

The way the PHP function/method/hook documentation works is by parsing the PHP source code and creating WordPress posts for every symbol. With every WordPress update this process is repeated and the posts are updated. This makes is possible to have user contributed notes and have extra documentation which is edited in a backend meta field.

This would be the way to setup the JavaScript documentation on developer.wordpress.org. The PHP code can be found at ​https://github.com/wordpress/phpdoc-parser. I have started a JS version on ​https://github.com/yoast/jsdoc-parser.

I investigated several solutions into parsing the JavaScript source code in WordPress. I tried both ​https://github.com/documentationjs and ​https://esdoc.org but both of these have failings. They both have a very hard time handling the JavaScript structure of WordPress core. JSDoc does this much better. And since JSDoc switched to babylon as their JS parser they can handle ES201* very fine now.

[herregroen]

I've just made ​https://github.com/WordPress/phpdoc-parser/pull/207 to update the phpdoc-parser used by developer.wordpress.org to support different languages in order to facilitate this.

This would allow the JSDoc template I've created ( ​https://github.com/herregroen/jsdoc-parser/ ) to potentially be used to create JSON exports of JSDoc which can then be imported by the phpdoc-parser without risking conflicts where PHP and JS functions have the same name.

Further work would need to be done on the wporg-developer theme to fully support this. Both the new programming language taxonomy as well as the already existing namespace taxonomy would have to be shown much more clearly in the interface.

Next to that the theme currently generates the source code snippets from the local filesystem, which works for WordPress itself but as the Gutenberg source code is still located on GitHub this is also something that would have to be accounted for.

[herregroen]

Regarding parsing the jsdoc using the JSDoc template I've created you can use the following JSDoc template with Gutenberg. This expects the jsdoc-parser to be located on the same level as the gutenberg directory.

jsdoc.conf.json:

{
  "plugins": [],
  "recurseDepth": 10,
  "source": {
    "include": ["packages/"],
    "exclude": [],
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "((^|\\/|\\\\)_|node_modules)"
  },
  "sourceType": "module",
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc","closure"]
  },
  "templates": {
    "packages": true,
    "packagesRoot": "packages/"
  },
  "opts": {
    "template": "../jsdoc-parser",
    "recurse": true
  }
}

Running jsdoc with that configuration ( jsdoc -c jsdoc.conf.json ) will generate a parsed-jsdoc.json file that can be imported using ​https://github.com/WordPress/phpdoc-parser with the wp parser import command.

This will generate posts in exactly the same manner as is already done for the PHP.

It should be noted that as mentioned above there's a few things lacking in both that plugin as well as the wporg-developer theme that would need to be addressed.

[oandregal]

I've tried this approach on Gutenberg code. Here's the PullRequest I've used as a playground to document my findings with specific code samples from Gutenberg: ​https://github.com/WordPress/gutenberg/pull/13637

The results weren't what I was expecting so I've tried to tweak it a bit to learn if they could be improved. I don't have a lot of jsdoc experience, so I haven't seen how.

In parallel, I was working on a package to generate Public API docs. Given a ESNext JavaScript file, it outputs a Markdown with its Public API. It takes a different route than this approach: it builds the Abstract Syntax Tree of the code, extracts the export declarations of a given file, and looks backwards from there to find the JSDoc comments up to the declaration. It contains an extensive test suite that hopefully is useful to understand how it works as well. It can be found at ​https://github.com/WordPress/gutenberg/pull/13329 I've tested it with every Gutenberg package and it works. It seems feasible within a reasonable timeline to improve that package and output a JSON tailored for developer.wordpress.org. From what I've seen, it basically needs to add file references (line numbers, names), and namespaces.

@herregroen @atimmer I was wondering whether you'd take a look at those PullRequests and let me know what do you think?

[oandregal]

Herre and I agreed to try the ​https://github.com/WordPress/gutenberg/pull/13329 approach and see where that takes us.

I'm going to prepare the doc generator to output the necessary information (file name, line numbers) and also to accept a formatter ala jsdoc templates. Herre will use that to create a JSON for developer.wordpress.org and will take care of the integration with our current systems.

[oandregal]

​https://github.com/WordPress/gutenberg/pull/13329 has been merged and it's already generating docs for Gutenberg (embedded in the package's README files at the moment).

The README contains examples and info on how to use it ​https://github.com/WordPress/gutenberg/tree/master/packages/docgen Please, ping me when you're ready to give it a try for creating the JS docs for core.