JavaScript Documentation Generator Showdown

Redfin has been working on making it easier to share common ui components between the different sites we own, and we need documentation available that makes it easy for new developers to use and contribute. Documentation generators parse existing source code for comments and create documents that can be used for reference. These documents are then used by developers to contribute to development, and to understand how to use the api. To produce the best docs for contributors, we did some serious considering and eventually found the winners.

Evaluation Criteria

Requirements

1. An un-opinionated doc framework: as our common components are fairly mature, we cannot be involved in a major code refactor to appease a documentation framework.
2. Links and references to tutorials that are maintained independent of code: many kinds of documentation belong in the code — params, return values — but many don’t, such as tutorials. We want them to be tightly coupled, but stored independently.
3. Links back to the source code: to encourage developers to not only use, but also contribute, it should be easy for developers to go from browsing the documentation to browsing the code from which it was generated, ideally on GitHub.
4. Graceful handling of ES6 and ES7 features, as well as jsx.

Nice to Have

1. Documentation coverage: you can’t improve what you don’t measure.
2. Customizable output format: it would be nice to have Redfin-styled docs.
3. Searchable docs: who even browses anymore?
4. Todo flagging: it will help recruit developers from feature teams to contribute to the project if there is an explicit list of things for them to do.

Structured vs Unstructured

Ideally, we’d like to auto-generate docs from the comments that already exist in the code base with minimal changes. The developers who have come before have done a good job documenting the existing code; using a doc tool should not require rewriting all of our comments. However, to facilitate searchability, documentation coverage, and well-documented contributions in the future, structured comments may actually be better in the long run.

What We Considered

ESDoc

Example

• Hosted example

Pros

• Documentation coverage
• Includes the source code in the docs
• Links directly to the source code from the docs

Cons

• Only documents ES6 classes exported as ES6 modules
• Embeds the README, but doesn’t seem to have capability for tutorials

Docco

Example

• Hosted example

Pros

• Dead simple
• No refactoring required

Cons

• Doesn’t support multi-line comments, with no intention of support ever. The main benefit of docco is that it is non-normative; why place such an arbitrary limitation?
• No search
• Hard to theme

Documentation.js

Example

• Hosted example

Pros

• Uses jsdoc syntax

Cons

• Doesn’t support jsx (currently under development, see: this issue that links to this upstream issue.
• Assumes that projects can be documented by crawling requires from a single entry point. We could likely work around this by documenting a spurious js file with just requires for server implementations and client implementations, but it does seem rather strange.
• No tutorial support
• No search         
• Arcane errors:

» documentation ./core/MyFile.js -o documentation -f html -g
assert.js:89
throw new assert.AssertionError({
^
AssertionError: did not recognize object of type "AssignmentPattern"


Follow it’s resolution here.

Aside: This seems to be a feature rather than a bug. See their wiki:documentation is an OPEN Open Source Project. This means that individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project, which makes their 44 open Github issues rather unsurprising.

YUIDoc

Pros

• Redfin-able: yuidoc –themedir ./mytheme allows you to specify overrides for your docs using handlebars.js templates.
• Outputs a mess of helpful warnings, but doesn’t hork!
• Search
• Links to source code
• Auto links to MDN.

Cons

• Will require fairly significant refactoring of existing comments (only the file we stole from Yahoo, History, output docs as-is).

What We Decided

Our clear winners were YUIdoc for api docs and Docco for annotated source code. We liked that YUIdoc is easily themeable, it gives tons of helpful warnings, and it runs as-is on our existing codebase.

However, ESDoc is awesome! I had never seen documentation coverage before, and the feature is amazing. The links to the source code are incredible, the default theme is beautiful.  Unfortunately, the requirement that everything has to be a ES6 module makes it nearly impossible to use for anything other than toy projects, and actually impossible for a large, legacy projects. Furthermore, we want to theme it with Redfin themes. Although different frameworks work for different projects and use cases, ESDoc ultimately wasn’t right for us, but I hope that someday it is.