Before releasing the HP Cloud JavaScript bindings we wanted to have them fully documented and have an web version of the API documentation available. We find this type of documentation to be very handy.
But, when I approached the packages for JavaScript it was a sad state of affairs compared to the tools available for other languages. What I can do with a tool chain like Doxygen is just not available in JavaScript.
After the first pass of analysis I narrowed it down to YUIDoc and JSDoc3. Let’s take a look at how they stack up.
JSDoc3
Intended to be an update to JSDoc2 (JsDoc Toolkit) this is a project not like other server side JavaScript projects I’ve worked with. To analyze the JavaScript and build the documentation it uses a modified version of Rhino, a JavaScript engine built in Java. While you can install it with npm it doesn’t actually use node.js. That means you need Java on your system.
JSDoc3 can pick up a certain amount about a codebase automatically. Some patterns in JavaScript, like CommonJS modules, need to be clearly documented. Being able to look at a codebase means it can generate reports on documentation coverage.
Quick List of Features:
- A nicely sized and thought out tag dictionary.
- Documentation coverage reports.
- Markdown support.
- Templates so you can apply your own design.
- Automated testing through Travis.
YUIDoc
It’s a system running on node.js and provides lots of functionality you’d come to expect out of the box including a server to view your documentation as you write it and a simple search feature.
YUIDoc doesn’t introspect the code. Everything needs to be explicitly documented down to the class and method names. This means there is more to document than JSDoc3 and no reports on coverage.
What YUIDoc provides is a much cleaner user interface out of the box. JSDoc felt like a system where I’d need to write my own user interface before I’d present it to the world. The interface on YUIDoc was one I liked and found usable. Navigating and understanding what was going on is important when figuring out an API and this interface makes it much easier.
Quick List of Features:
- Simple search.
- Built in server to view documentation as you write it.
- Markdown support.
- Templates so you can apply your own design.
- Automated testing through Travis.
How We Picked
Imagine being stuck between these. Coverage reports and a little bit less documentation but major UI work (I can do UI work) or a nice UI and extra features like calling out which elements are chainable. Did I mention, you can do that in YUIDoc. Both systems are at a comparable level but have some notable differences.
Now, Imagine a couple developers and a coin. Some decisions are easier than you think.