Choosing a JavaScript Documentation Generator – JSDoc vs YUIDoc vs Doxx vs Docco

JavaScript Documentation Generators

Recently, we had to choose a JavaScript document generator tool for documenting APIs of various FusionCharts products. API documentation is different from normal documentation because API documentation is generated directly from the source code by reading the comments written in the source code.

Our requirement was pretty straight-forward — the tool should help us write sustainable code and prove to be a good support in the long run. We evaluated different document generators in the process to find which one best suited our purpose. After thoroughly studying tools like JSDoc, Docco, Doxx and YUIDoc, we decided to use JSDoc. This article talks about why we chose JSDoc over other available utilities and why JSDoc can be a powerful tool for a JavaScript developer.

The criteria we considered in our evaluation

The factors we considered in our evaluation were quite rigorous. We needed to ensure that the tool we choose would perform well in the long run and generate API docs that were useful to the end user. These were the questions we had in mind when evaluating the candidates:

  • Does the tool support structured syntax, like Javadoc or PHPDoc syntax?
  • Can we add additional documentation to the API docs, like tutorials, README?
  • Can we customize the appearance of the output?
  • Is there any search feature in the output?
  • Is the output HTML SEO friendly?
  • Does it require external dependencies?
  • Does it parse the entire source code or just the comment blocks?

How we proceeded with the evaluation

We wrote a small JavaScript file, which is a Directed Graph data structure and prepared it for documentation with each tool — for JSDoc, Docco, Doxx and YUIDoc. Next, we ran each tool on its respective source and produced output for each tool. For JSDoc, we used the inbuilt JSDoc template and Docstrap, a Twitter Bootstrap based template for JSDoc. For Doxx, Docco and YuiDoc, we used the inbuilt templates.

We measured the time each tool took to run each tool using the time command from commandline. The testing was done on a MacBook Pro with 2.4 GHz Intel Core i5 processor and 8GB DDR3 RAM, running OS X version 10.9.

What we evaluated

Support for structured syntax

While writing documentation in comment blocks, it is absolutely necessary to write it in a specific format. This enforces a pattern of writing comments. Javadoc and PHPDoc syntaxes have been in use for a long time and have gained a good number of users because of the easy-to-maintain structure. For example, for each function, its parameters and return values are neatly documented using specific tags in the comment.

An example of this type of syntax is:

This is where we found Docco to be severely lacking. Docco is built from the ground up for good looking documentation – easy and fast. It will parse any comment line beginning with double slashes and place it alongside the actual source code in the output.

The equivalent of the code above for Docco will be:

However, as more and more contributors start working on the same code, each coder will tend to write the function or class descriptions differently in the comment, depending on each person’s choice and style. This brings wide disparity in the ways in which the code is documented. As a side effect, when the project grows, the code cannot be properly parsed through a structured document generator.

Specifying function or method parameters, return values, description and examples in a specified style in the comment also makes it easier for anyone looking at the code to understand what the function does, without having to read the code block. This is particularly useful for long running projects where team members can keep changing. Newcomers can easily adapt to an existing structure and understand how the pre-existing code works.

Interestingly, YUIDoc requires the names of functions/methods/properties to be explicitly written in the comment. This is because YUIDoc reads through the comment blocks only, ignoring whatever is outside those blocks.

The same function would be written like this for YUIDoc:

Notice the addition of @class tag. YUIDoc scans this tag to get the name of the function. It is slightly odd to document standalone functions as @class. There is already a feature request made in YUIDoc to implement @function tag for standalone functions like this.

The only downside of enforcing a structured syntax is that it brings in a steeper learning curve. Docco can be used any new developer easily, without taking any effort to learn a new syntax. JSDoc and YUIDoc require developers to read and have a good understanding of the syntax of structured commenting before they can use it. This implies having to learn the tags, their arguments and styles and gradually getting use to the style of writing comments in code.

Visual appeal

YUIDoc excels in the accessibility of the stock themes that it provides. The output is readable, searchable and is user-friendly, even for the non-technical users. JSDoc, on the other hand, provides nothing more than a output of all the API objects in a linear way. This makes it harder for non-technical users to find information and make full use of the output.

Being bundled with Twitter Bootstrap, the output of Doxx looks very neat and well organised. They have also done a good job with the sidebar, which highlights the section you are in as you scroll down the page.

Docco does a decent job in theming and produces a neat output.

Customizing the output design

Everyone loves good designs, and it is extremely important that the generated documentation looks clean and is accessible. Doxx, Docco and YUIDoc clearly have an edge here for producing neat outputs that look beautiful out of the box. But what if we want to brand the API output or change the design to our liking?

By default, JSDoc’s output is not pretty, even if it produces scores of useful information. JSDoc bypasses this limitation by allowing adding a custom CSS file to the generated output to tweak the way it would look. In the hands of an able programmer, this can work wonders. This approach also allows creating reusable themes that can be plugged in to any JSDoc-dependent project. An example of this the Docstrap template, which gives a Bootstrap loaded theme package for JSDoc. We gave Docstrap a try, and found it to be good enough to make JSDoc output better. There is still a good scope of improvement.

Search feature for the generated documentation

Among the tools we evaluated, only YUIDoc provides a nifty search feature out of the box that helps users search through the documentation. This is useful in finding any variable, method or class from anywhere in the documentation. It increases accessibility and discoverability of the API by a good margin. Others do not provide a search feature, at least with the default template. It is possible to add search option by customizing the themes for any of these tools.

Adding additional documentation like tutorials, README to the API docs

Tools like Sphinx for Python, which are not JavaScript-based, allow adding additional documents to the generated API docs. In Sphinx, additional files can be included along with the source code. Using this, normal API documentations can be enhanced by adding extended descriptions, examples and use cases to the documentation output. We looked for its JavaScript equivalent, and found JSDoc provides this feature. Extra documentation pages can be written in Markdown syntax and linked from the comments through the @tutorial tag. This produces interlinked tutorials for a specific method and comes in very handy when explaining something complex to the end user.

SEO friendly output

The main purpose of generating API docs is to let the world know how your code works and how they can interact with it. So visibility of those docs in search engines is highly desired. In comparison to other tools, we found the outputs of Docco and YUIDoc to be really good for search engines. YUIDoc particularly has solid SEO foundations for its generated documentation, improved with metadata and microdata.

By default, JSDoc’s output is not SEO-friendly. Using Docstrap, it is possible to get slightly more SEO friendly documentation. However, if a documentation generator allows you to customize its output, then it is always possible to improve the output by adding the meta information that search engines look for.

External dependencies

The lesser the number of external dependencies of a project, the easier it is to manage that project in the long run. This helps in keeping a project as lightweight as possible, yet having all the powers it needs. Keeping this in mind, we found all the four tools to be extremely useful because of the minimal dependency chain they have. All of them can be installed through the NPM, the Nodejs package manager.

Using Docstrap with JSDoc adds some complexity to the scene as Docstrap requires a build process to generate the CSS files.

Extensibility

Extensibility is the capacity of a program to allow itself to be augmented with additional features through a plug-in like system. JSDoc is highly extensible. The source code repository of JSDoc has a folder with various plugins that can be used with it. There are neat instructions of how one can develop new plugins for JSDoc. This can be very useful if someone wants to add new features to JSDoc, like adding support for some new tags which do not exist in core JSDoc.

YUIDoc does not have a strong API like JSDoc for extending it, but it has a neat way of creating new themes. A couple of sample themes are shipped with YUIDoc. These can be used as base for new themes.

Parsing source code

This was the final and the most important feature we were looking for and this turned out to be the ultimate selling point for JSDoc. All other documentation generators parse only the comment blocks, ignoring the rest of the source code, and generate their output based on the comments only, structured or not.

If a documentation generator reads only the comment blocks, it can possibly generate API docs from a source code containing only comments and no code. The resulting API documentation will look complete because all the objects are documented. It is still useless and, often misleading, because there is no code for those documented methods. If a user tries to use the API by reading that documentation, he/she will find that the methods he/she is trying to call do not exist at all!

Tightly coupling source code with the documentation in comments also results in less lines of code. There is no need to write the name of the objects in that case. The documentation generator will pick up the name by studying the source.

Hence, we strongly favour close coupling of code and its documentation. One should not exist without the other.

JSDoc is more than just a comment reader – it is a language parser. It produces the output by actually scanning through the code and parsing the entire source tree. It closely links the documentation with the rest of source code and identifies comments with the code blocks by looking at the code. This makes it an extremely powerful tool, despite it shortcomings of not having an attractive interface out of the box, or not having a highly SEO friendly output. The creators of JSDoc have put their minds to the more important aspect of creating a tool that reads and understands JavaScript. They have left the task of beautifying the produced result to the users. In our opinion, that makes full sense.

The Final Call

Considering all these factors, we have chosen JSDoc as the documentation generator tool of our choice. We plan to extend its interface and make the outputs prettier. We also have ideas of exploiting the language parser in JSDoc and create some interesting products.

We love tools which help us automate tasks. But we love those tools even more which let us control the automation.

Visual Comparison

JSDoc

YUIDoc

Doxx

Docco

Syntax

Structured

Structured

Structured

Unstructured

Accessibility
(default theme)

Low

High

High

High

Search feature

Yes, not by default

Yes

No

No

Extra themes

Docstrap

One bundled. Others available.

No.

Bundled

Learning curve

Medium

Medium

Low

None

Source parsing

Yes

No

No

No

Customization

High

Medium

Low

Very low

Extensibility

High

Medium

Low

None

Speed

Medium

Low

N/A

Very High

  • Sean Jacke March 5, 2014, 1:46 am

    Thanks for the analysis!
    Just wanted to mention that the alignment is off in the columns of the “Visual Comparison” table at the end of the post, making it pretty tough to decipher.

  • twain March 5, 2014, 1:54 pm

    Thanks for the alert. It’s fixed now!

  • Tim Brandin May 25, 2014, 2:55 pm

    Nice article! I like the way your breaking down the comparison, going to take all this into consideration for a Meteor APIDocs application we’re just starting to think about.
    https://trello.com/b/Fp9P2sDt/apidocs-meteor-com

    • Kaustav Das Modak May 26, 2014, 12:37 pm

      Glad it helped you, Tim. Hoping to see apidocs.meteor.com live soon!

  • Dave August 6, 2014, 7:50 am

    Great article. Really helped me make a speedy choice (JSDoc). Thanks

  • adampasz August 27, 2014, 10:27 pm

    I agree. I looked at a bunch of options (including jsduck) and jsdoc ended up producing the best results with the way my code was structured.

    I like that jsdoc is native js (node-based) and doesn’t require Ruby. It makes it easy to integrate with the rest of my project, and it doesn’t introduce dependencies on other languages and tools.

    Smart comments also proved helpful!
    http://smartcomments.github.io

  • Sebastián Gurin September 14, 2014, 7:36 pm

    Just created a new jsdoc tool that attack many of the problems I found in tools like yuidoc and jsdocs. https://github.com/cancerberoSgx/short-jsdoc

    • Frederik Krautwald May 27, 2015, 9:26 pm

      When do expect this to be ready for production?

  • Yassein October 23, 2014, 2:48 pm

    Thnaks a lot 🙂

  • Georg Schlenkhoff June 18, 2015, 2:28 am

    Hello, I’ve created a new module that generates JSDoc documentations on the fly: http://dokkerjs.com/

  • Simon sass October 31, 2015, 7:01 pm

    Good for all levels, thank

  • homer0 November 13, 2015, 5:13 am

    Just wondering, did you take a look at ESDoc.org? I’ve been using it for a couple projects now and I’m very happy with it.
    This is not a “did you see that? Because it’s better than this” kind of comment :P, I really want to know if I should migrate.

    Thanks!

  • Oğuz Çelikdemir November 15, 2015, 1:05 pm

    I just wanted to know that have you check Sencha JsDuck javascript document generator?

Leave a Comment