Either of the two preceding approaches are enough for most programmers to reap the benefits of documentation without having to spend too much time writing it. However, if you are looking for a more universal structure to your documentation, or if you and your team are not the documentation's only audience, then it might be beneficial to use an external tool such as JSDoc or Docco.
In larger organizations, it's not uncommon to have different teams working on different parts of the code. When one team needs to use a component or library that another team manages, the first team may not want to read the second team's code, or for that matter, they might not even have access to it themselves. Robust documentation can be useful in these cases by providing a way for teams to understand each other's code without having to read it directly.
Another important scenario is user customization. With the robust and powerful applications that Backbone enables, it often is only a matter of time before a customer requests a way to customize something or, if they can't write JavaScript themselves, have a consultant customize it for them. In these cases, the best solution is often to expose a subset of the code for the customer to work with, and this public customization API will require documentation so that the customer (or their contractor) can learn how to use it.
In either of these cases, a tool such as JSDoc or Docco can be used to generate separate documentation files that can be shared without sharing the code itself. However, at the same time, developers can still write their documentation along with their code; there's no need for them to maintain (for instance) a separate MS Word document.
Many teams also use the structure of JSDoc within their documentation, without ever actually using this tool to generate externally facing documentation. For these teams, the main benefit of JSDoc lies in its annotations, which let the teams write documentation in a similar manner and in a way that future team members are more likely to understand.
JSDoc (http://www.usejsdoc.org) is the oldest and most popular JavaScript documentation tool available. As far back as 1999, before the JSDoc tool even existed, developers used its syntax (borrowed from JavaDoc) to document the very early JavaScript code. The JSDoc tool itself, now in its third edition, is incorporated into several different other tools (including Google's Closure compiler), and support for its syntax can be found in almost every major code editor from Sublime to Eclipse to Visual Studio.
Using JSDoc, a developer can easily convert his inline documentation into external HTML files, as shown in the following screenshot:
.jpg)
JSDoc works by relying on annotations included in documentation strings. For instance, consider the following code:
/**
* This ""bar"" method takes a ""Baz"" argument and does bar stuff
*/
bar: function(baz) {
doBarStuffWith(baz);
}Instead of using the above code, a developer using JSDoc would use an @param annotation, as follows:
/**
* Does bar stuff
* @param {Baz} baz this argument is used to do bar stuff
*/
bar: function(baz) {
doBarStuffWith(baz);
}The "@param annotation tells JSDoc that the method takes a baz argument and that it should be an instance of the "Baz" class. The full list of annotations can be found on the JSDoc website, and they are fairly straightforward, so we won't discuss all of them here. However, two of them (@property and @param) can be slightly problematic when used with the Backbone code, so let's examine how to use them properly.
Let's imagine that we want to document a Backbone Model. For doing so, we might write the following code:
/**
* This model represents a book in our application.
* @class
*/
var Book = Backbone.Model({ ...Now, let's assume that our Book Model can have three different attributes: title, description, and page length. Now, the problem is how do we document them? There is no @attribute annotation in JSDoc since attributes are Backbone-specific and the @param annotation can seemingly only specify the argument of a single attribute; it can't (for example) tell us that two of the attributes should be strings and the others should be integers.
Luckily, one can use multiple @param or @property annotations to solve this problem (which one you use is up to you; because Backbone creates properties for both attributes and options, both are in fact parameters and properties). Consider the following:
/**
* This model represents a book in our application.
* @param {object} attributes
* @param {string} attributes.title book's title
* @param {string} attributes.description description of the book
* @param {integer} attributes.pageLength number of pages
*/Book = Backbone.Model({ ...If you are using JSDoc informally (that is, you don't plan to generate external documentation), you can even simplify the above slightly by leaving out the initial @param {object} attribute annotation.
Docco(http://jashkenas.github.io/docco/) is notable both because it takes a very different approach from JSDoc and because it was written by the creator of Backbone itself (Jeremy Ashkenas). Unlike JSDoc, which focuses on creating API documentation, Docco focuses on generating tutorials and/or explanations of how a given block of code works. Docco also differs from JSDoc in that it uses single-line comments, rather than multiline ones, to generate its documentation.
Here's an example of documentation generated using Docco; in fact, it was generated using Backbone's own source code (you can find the original version on the Backbone website):
.jpg)
As you can see from the preceding example, Docco generates documentation with two columns. On the right is the original source code being documented, minus any comments, and on the left are the comments that correspond to this source code. For example, here are the original lines from Backbone that were used to generate the preceding example:
// Backbone.js 1.1.2
// (c) 2010-2014 Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors
// Backbone may be freely distributed under the MIT license.
// For all details and documentation:
// http://backbonejs.org
(function(root, factory) {
// Set up Backbone appropriately for the environment. Start with AMD.
if (typeof define === 'function' && define.amd) {
define(['underscore', 'jquery', 'exports'], function(_, $, exports) {
// Export global even in AMD case in case this script is loaded with
// others that may still expect a global Backbone.
root.Backbone = factory(root, exports, _, $);
});
// Next for Node.js or CommonJS. jQuery may not be needed as a module.
} else if (typeof exports !== 'undefined') {
var _ = require('underscore'),
factory(root, exports, _);
// Finally, as a browser global.
} else {
root.Backbone = factory(root, {}, root._, (root.jQuery || root.Zepto || root.ender || root.$));
}
}(this, function(root, Backbone, _, $) {
// Initial Setup
// -------------
// Save the previous value of the `Backbone` variable, so that it can be
// restored later on, if `noConflict` is used.
var previousBackbone = root.Backbone;A key part of Docco's appeal is just how simple it is: There are no annotations or even multiline comments, just plain old // single-line comments. Docco is also valuable because of the type of documentation it generates: If you want to create a tutorial or walk through of your code Docco is a much better choice than JSDoc.
Ultimately which documentation system or systems you use will depend on your needs and future expectations. Even if you opt for simple documentation, it is important that you not underestimate the need to properly document your code. If you do, your future self (and possibly your coworkers) will regret it.
Of course, as with most things in programming, it is also possible to have too much documentation. When adding documentation, you should always remember that as you refactor and update your code, any documentation written for that code must similarly be updated. This certainly shouldn't stop you from adding documentation, given its many benefits, but before we move on to testing (which shares the same downside), we'd be remiss not to mention this ongoing maintenance cost.