User:JHernandez (WMF)/JS documentation tools

Comparison between JS documentation systems. See T146917 and parent tasks.

Generated tests

 * Based on POCs, over MobileFrontend, only fixed View.js, Overlay.js and AbuseFilterOverlay for research purposes
 * JSDOC
 * Live docs: http://mobilefrontend-jsdoc-test.surge.sh/
 * POC: https://gerrit.wikimedia.org/r/#/c/357202/
 * Documentation.js
 * Live docs: http://mobilefrontend-documentationjs-test.surge.sh/
 * POC: https://gerrit.wikimedia.org/r/357583

Comparisons
This table uses unicode (emoji) characters

Recommendations
There are 2 things to consider when talking about this: They are some times tied together (jsduck and yuidocs have custom syntax and tooling) and sometimes not (jsdoc as a spec and jsdoc & others as tools).
 * Which documentation format to use (spec on comment syntax and tags for documenting code)
 * Which tool and/or template to use to generate readable HTML docs

I believe it is worth considering them separately:

Which documentation format to use (spec on comment syntax and tags for documenting code)
The community seems to have standardized around JSDoc as the comment syntax and format to document JavaScript. There are competing implementations/parsers (jsdoc3/jsdoc, eslint/doctrine) around a single spec (http://usejsdoc.org/).

The syntax is updated to support the latest JavaScript specs (like ES2015) and it is widely used.

In contrast, jsduck created its own syntax which with is tied and only used in jsduck. It solved necessary problems at its time, but it is now only used there and obsolete.

I think we should move to the jsdoc syntax for documentation comments.

Which tool and/or template to use to generate readable HTML docs
Documentation.js is a nice effort, specially the multiple output formats, but it seems worse than normal JSDoc and has less activity/maintainers, so it doesn't seem like we should rely on it.

esdoc is in 0.x versions and still evolving, and only supports modern JavaScript, so it wouldn't be useful for us.

jsduck has good tooling and documentation validation, we know it and have a lot of code written using it. The HTML template is very well featured and usable. It is also unmaintained so it won't be updated to newer JS features/syntax.

JSDoc seems like the best option, see the comparison table.
 * Pros
 * Supports modules and namespaces
 * Doesn't rely on Ruby
 * Additional features like tutorials, type definitions, interfaces, modules
 * Seems more future proof


 * Cons
 * The default template is not very usable or readable, we need to find a better one and/or fork one and adapt it to our needs
 * On the plus side, there are a few recommended that are better, more featured and readable:
 * docstrap
 * jsdoc3Template
 * minami
 * docdash
 * It uses JSDoc syntax, and our code is in JSDuck syntax. There are subtle differences, so there is a migration cost and a slight learning curve for developers
 * Documentation validation may not be as strict as jsduck's one
 * There is eslint valid-jsdoc which is used and works, and it fits our move to eslint. Unsure about how strictly it validates docs

What to do?
It depends on how willing we are to accept the tradeoffs (different syntax, migration cost and some learning curve mainly).

Ideally, we do accept it is a change, and then for new projects we use JSDoc and make a plan to migrate existing ones.

This should be discussed more on the front-end standards group.