One common divisive point among programmers is on the importance of code comments. Some maintain that code is not complete until it is fully commented. Others maintain that well-written code should require no extra information – it is self-documenting. Whichever side of the fence you fall on, sometimes you find yourself in need of generating documentation based on your code – for example, when writing an API that will be consumed in a black-box manner. The Back& team looked at a number of different documentation products for JavaScript projects. Here’s what we found.

NGDoc

AngularJS relies upon a flavor of JSDoc known as NGDoc. NGDoc builds off the features offered in JSDoc by adding several angular-specific comment directives that can be added to your class and function headers. These allow your documentation to mirror the code more accurately, particularly given that AngularJS apps tend to have an architecture that differs significantly from many other types of web apps. NGDoc documentation is usually built using Grunt.

Docco

Docco is a quick-and-dirty documentation scheme that handles markdown format as well as syntax highlighting for JavaScript. It is highly configurable, which both makes it flexible and gives it a steep learning curve. One of the benefits of Docco is that it is not strictly restricted to JavaScript – versions of the library exist for Ruby, Python, Clojure, and more. Docco is typically run from the command line as its own tool, so it can likely be integrated into most build and deployment scripts.

Doxx

Doxx is a documentation product focused on creating beautiful HTML documentation. It relies upon HTML templates and CSS to create the resulting documentation, which is based off of Twitter Bootstrap, and offers syntax highlighting through the use of Prism.js. It can be used for JavaScript or CoffeeScript, and is most often built using Grunt.

YUIDoc

YUIDoc is a Node.js application that uses syntax similar to Javadoc and Doxygen to generate HTML documentation for your code. It features live previews, support for Markdown syntax, and support for a large number of languages. It is installed as a third-party tool and run from the command line at the root of your project’s source code folder. While it was originally developed for the YUI project, it can be used on any project whose language uses /* …. */ for comments.

Conclusion

Choosing an automated documentation tool is often a question of preference. Many developers tend towards using what they have worked with in the past, while others are always looking for the next great framework that will solve all of their concerns. While neither approach is advisable 100% of the time, there is some feature differentiation among these products that, on the surface, all do exactly the same thing. In this respect NGDoc, with its native support for many of Angular’s features, is often a good choice for AngularJS applications. That being said, directive support may not necessarily be the primary goal with your documentation. Ultimately, the best documentation product is the product that most accurately reflects the documentation you wish your user to see, so the best choice may simply be “whatever works.”

Get a free hosted AngularJS backend with features such as user management, social signin, payment integration, security and more – GET STARTED NOW.