Choosing the Right JavaScript Documentation Generator

We recently had to select a JavaScript document generator tool to document the APIs of various FusionCharts products. API documentation differs from routine documentation in that it is generated directly from the source code by reading the comments that are written in the source code. Our requirement was simple: the tool should assist us in writing long-lasting code and be a valuable resource in the long run. Throughout the process, we evaluated various document generators to determine which one best suited our needs. We chose JSDoc after thoroughly researching tools such as Docco, Doxx, and YUIDoc. In this article, we’ll discuss why we chose JSDoc over other available utilities and how JSDoc can be a useful tool for JavaScript developers. You may use Data Visualization Tool to compare JavaScript charting libraries and showcase all possible pros and cons of the JavaScript libraries for creating charts, which will help you choose the best charting library for your data visualization.

Our Evaluation Criteria

The factors we considered in our evaluation were quite rigorous. We needed to ensure that the tool we chose would perform well in the long run and generate helpful API docs for 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 Conducted the Evaluation

We wrote a small JavaScript file, 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 the commandline. The testing was done on a MacBook Pro with a 2.4 GHz Intel Core i5 processor and 8GB DDR3 RAM, running OS X version 10.9.

What We Evaluated

Support for the Structured Syntax

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

Comparison

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;
}

Collaboration

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 how the code is documented. As a side effect, the code cannot be appropriately parsed through a structured document generator when the project grows. Specifying function or method parameters, return values, description, and examples in a specified style in the comment makes it easier for anyone looking at the code to understand what the function does without reading the code block. This is particularly useful for long-running projects where team members can keep changing. Newcomers can quickly 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 the @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 the @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 by any new developer easily, without making any effort to learn a new syntax. JSDoc and YUIDoc require developers to read and understand the syntax of structured commenting before they can use it. This implies learning the tags, their arguments, and styles and gradually getting used 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 non-technical users. JSDoc, on the other hand, provides nothing more than an 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 organized. They have also done an excellent 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 essential that the generated documentation looks clean and is accessible. Doxx, Docco, and YUIDoc 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 helpful 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 the creation of reusable themes that you can plug into any JSDoc-dependent project. An example of this is 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.

The 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 the 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 a search option by customizing the themes for any of these tools.

Adding Additional Documentation 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. With this feature, you can enhance routine API documentation 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 is very handy when explaining something complex to the end-user.

SEO-Friendly Output

The primary 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 perfect 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, it is always possible to improve it by adding the meta-information that search engines seek.

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 four tools extremely useful because of their minimal dependency chain. You can install all of them through the NPM, the Nodejs package manager. Using Docstrap with JSDoc adds 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 you can use with it. There are neat instructions on 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 robust 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. You can use them as a base for new themes.

Parsing the 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 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, they will find that the ways they are trying to call do not exist! Tightly coupling source code with the documentation in comments also results in fewer 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 favor the 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 the source code and identifies comments with the code blocks by looking at the code. Despite its shortcomings, this makes it a potent tool of not having an attractive interface out of the box or a highly SEO-friendly output. The creators of JSDoc have put their minds to the more critical 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 complete 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. Also, we have ideas of exploiting the language parser in JSDoc and creating some exciting products. We love tools that 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 are 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