Note! This article is part of a series. In prior articles we wrote a small JavaScript application. We string tested the application, verified syntax and tested performance ( see here). In this installation, we will document our program.

We need to qualify what type of documentation we are referring to. In this case, it's "internal documentation". We are describing "how" the program works internally. The intended audience is other programmers. If we were working on a project where we expected other programmers to use and extend our program, we would refer to this as an Application Programming Interface (API). In fact, most projects, when successful are subject to change, enhancements and new team member. Thus, most "internal documentation" is referred to as API documentation.

Let's introduce another tool, jsdoc here: https://github.com/jsdoc3/jsdoc). JsDoc is a documentation processor.

Let's edit our JavaScript application and annotate the source.

JSDoc works the same way a lot of documentation tools work. Virtually all programming language allow a programmer to include "comments" in a programming. A comment is a note intended to read by other human beings. Most documentation tools read through a program listing and select the "comment" blocks. The documentation tool then looks for special characters, usually referred to as "tags", to identify content intended to be published as "documentation".

Similar tools would be JavaDoc Tool for Java (http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/index.html). Doxygen for C, C++, PHP
and other languages (see http://www.stack.nl/~dimitri/doxygen/index.html).

To use JSDoc we need the tag reference located here: https://code.google.com/p/jsdoc-toolkit/wiki/TagReference.
Here is our updated source:

/** Person entity.
 * @property {string} first_name  given name of person
 * @property {string} last_name  family name
 * @constructor
 * @class
 */
var person = function(first_name,last_name) {
    /** @description init populates our first_name and last_name properties.
     */
    this.init = function(first_name,last_name) {
        if (first_name) {
            this.first_name = first_name;
        };
        if (last_name) {
            this.last_name = last_name;
        };
    };
    /** Gets the first_name property value.
     *   @returns {string} first_name The first_name property value.
     */
    this.getFirstName = function() {
        return this.first_name;
    };
    /** Sets the first_name property
     *   @param {string} first_name given name value.
     */
    this.setFirstName=function(first_name) {
        this.first_name = first_name;
    };
    /** @function
     *   @returns {string} this.last_name the last_name property.
    */
     this.getLastName = function() {
        return this.last_name;
    };
    /** Sets the last_name property
    *   @param {string} family name value
    */
    this.setLastName= function(last_name) {
        this.last_name = last_name;
    };
    /** executes our init method. */
    this.init(first_name,last_name);
};
/** An person instance.
 *  We will use this instance as a set up for our
 *  performance tests.
 */
var joe = new person("joe","smoe");

/** A test case. Get the value of
 *  our person's first name. Print
 *  it to the console.
 */
var firstName = null;
firstName = joe.getFirstName();
console.log(firstName);

/** A test case. This test case also
 * gets a value. However, we surround
 * the statement in a try/catch block.
 */
var lastName = null;
try {
    lastName = joe.getLastName();
    console.log(lastName);
} catch(error) {
    console.log("An error occured");
}

Next, Create a directory for your API docs:

$workspace>mkdir docs
$workspace>mkdir docs/api

Let's create a short README file in the docs directory. The contents of the README file will serve as a cover sheet to our documentation set.

$workspace> cd docs
$workspace> echo "This short program serves as an example and as a peformance test case." > README
$workspace> ls
api  README

Here is our command line. This instructs JsDoc to produce our internal API document set:

$workspace> cd $HOME/dev/jsdoc
$dev/jsdoc>./jsdoc -d /worspace/docs/api /workspace/person.js /workspace/docs/README

A brief explanation of the command line:

"./jsdoc" is the jsdoc program (and we are executing it).

-d tells jsdoc where to create our documents.

person.js is our program listing. We need to include the full path to where person.hs resides.

The last option instructs jsdoc to add the contents of our README file in the index.html file of documentation set. In other words, the README file contents become the "cover sheet" for document set.

You can peruse the generated documentation here.

Once you figure out how to generate to document set, reproducing and updating the documentation is pretty easy. What you also find is, the documentation allows to you review the program structure as it changes during the project life cycle.

When we introduced the term "internal documentation", we said the audience was "other programmers". Actually, the internal documentation is great tool even for a project with one sole programmer. I often discover changes I want to make simply by documenting by my own code.

In addition, some projects have long life times. The team moves on. When the team revisits a project, the "internal documentation" is a great refresher course.

To summarize, jsdoc is great tool to have in your JavaScript programmer's tool chest.

About the Author:
Lorin M Klugman is an experienced developer focused on new technology.
Open for work (contract or hire).
Drop Lorin a note. Click here for address.
Please no recruiters :)
- Home