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:

/** * Takes a number and returns its square value * * @param {number} num - The number for squaring * @return {number} */ var square = function (num) { return num * num; }

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:

// Takes a number and returns its square value var square = function (num) { return num * num; }

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:

/** * Takes a number and returns its square value * * @class square * @param {number} num - The number for squaring * @return {number} */ var square = function (num) { return num * num; }

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