Jump to content

User:JHernandez (WMF)/JS documentation tools

From mediawiki.org

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

Generated tests

[edit]

Comparisons

[edit]

This table uses unicode (emoji) characters

JSDuck JSDoc Documentation.js
Must have (from JSDuck)
User-friendly interface ✔️ ✔️⚠️

Depending on template

✔️⚠️

Depending on template

Search feature

Client-side, serverless

✔️ ✔️⚠️

Depending on template

✔️
Stable permalinks to classes and methods ✔️ ✔️ ✔️ Hash fragment urls
Support Markdown for all text content ✔️ ✔️ Markdown plugin ✔️
Easy discovery

Browsable class hierarchy

e.g. "mw.Title" nested in "mw" in sidebar

✔️ ✔️ With proper tags: ✔️⚠️

Like JSDoc, but default template shows a flat sidebar with some nesting (example)

Support for class inheritance and mixins

Docs include inherited members by default

✔️ ✔️ ✔️ Like JSDoc
Support for singletons ✔️ ✔️⚠️
  • No @singleton
  • Can be documented with @namespace & @property
 ✔️⚠️ Like JSDoc
Support for private members ✔️ ✔️ @private ✔️ Like JSDoc
Support for static members ✔️ ✔️ @static ✔️ Like JSDoc
Support for events ✔️ ✔️ @listens @fires @event ✔️ Like JSDoc
Support for emitted events (@fires) ✔️ ✔️ @fires ✔️ Like JSDoc
Support for private classes ✔️ ✔️⚠️
  • @private
  • --private command-line option to include them in the output
 ✔️⚠️ Like JSDoc
Nice to have
Toggling private members and classes

Hidden by default

✔️ ❌ default template is pretty raw, and other templates have less features ❌ Like JSDoc
Shows in which file(s) a class is defined ✔️ ✔️ ✔️⚠️ Links to github by configuring --github
Each class page show class hierarchy and mixins ✔️ ✔️⚠️

Shows direct extends and mixins after the class definition (example)

✔️⚠️ Like JSDoc
Live examples in the context of documentation

Useful to help understand how it works and what to use

✔️ ✔️ @example ✔️ Like JSDoc
Classes organised by group, on the homepage

"Categories"

✔️ ✔️ Can set markdown file as home page

Classes can be organized on namespaces or modules with @namespace & @module

✔️ Like JSDoc, and can create a TOC in the configuration file
Easy to extend with additional tags

@context, @see, @since, etc.

✔️ ✔️ ✔️
Intelligent linking to mentioned classes and methods

Foo bar #baz

✔️ ✔️ ✔️
Support for documenting properties of parameters that are objects ✔️ ✔️ @property (example) ✔️ @property (example)
Support for documenting properties of returned objects ✔️ ✔️ @typedef and @property ✔️ Like JSDoc
Support for documenting callback parameters ✔️ ✔️ @callback ✔️ Like JSDoc
Support for documenting upstream code with pure comments

"jsduck.external.js"

✔️ ✔️ @external @typedef @interface ✔️ Like JSDoc
Support for class aliases ✔️ ✔️ @alias and @name ✔️ Like JSDoc
Type validation

Unknown param or return type produces an error

✔️ ✔️⚠️ eslint valid-jsdoc unsure about other errors ✔️ Like JSDoc
Limitations
Event names cannot contain dots
  • jsduck #497
  • wikipage.content documented as wikipage_content
 ❌ ⚠️

Can be done, but needs workarounds like wrapping event name in quotes, which are outputted https://github.com/jsdoc3/jsdoc/issues/523

example

⚠️ Like JSDoc, far from optimal
There cannot be a class and singleton with the same case-insensitive name
  • jsduck #304 
  • mw.notification and mw.Notification
    • Documented as mw.Notification_
 ❌ ✔️ example ✔️ example
Concept of "modules"
  • Which would allow grouping classes together
  • And methods to be documented as being part of a module
    • Without having a global class
      • e.g. module.exports
 ❌ ✔️ @module @namespace ✔️ Like JSDoc
Actively maintained ❌ ✔️⚠️
  • contributions have been slowing down the last 2 years
  • Issues are being responded to
  • Seems to have support for ES2015
 ✔️ Continuous development in the last 2 years

Supports and tested with latest JS features and libraries

Written for Ruby instead of Node.js ❌ ✔️ Written for JS ✔️ Like JSDoc
No support for ES6 syntax. T156469. jsduck #630 ❌ ✔️ Apparently yes

http://usejsdoc.org/howto-es2015-modules.html

http://usejsdoc.org/howto-es2015-classes.html

✔️ Like JSDoc
Others
Markdown tutorial files ❌ ✔️ about-tutorials ⚠️ Not directly, but can export to markdown and join files with tutorials and use something else to generate HTML site
Multiple output formats ❌ html ❌ html ✔️ markdown + remarkup + json + html

Recommendations

[edit]

There are 2 things to consider when talking about this:

  • 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

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).

I believe it is worth considering them separately:

Which documentation format to use (spec on comment syntax and tags for documenting code)

[edit]

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

[edit]

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
    • 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?

[edit]

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.

Retrieved from "https://www.mediawiki.org/w/index.php?title=User:JHernandez_(WMF)/JS_documentation_tools&oldid=2485343"