Creating rich documentation with JSDoc

In our last example, we will automatically create documentation for OpenLayers 3. As we saw in ellipsoid.js, the headers resemble to the structure of the API documentation. The explanation is simple: Closure Compiler and JSDoc use the same headers to compile the library and create documentation for them. When we extended the constructor and the vincentyDsitance method with the @api tag, we not only make them exportable but also define that they should appear in the API documentation.

JSDoc is defined as an OpenLayers 3 dependency; therefore, it can be found in the node_modules folder. We will use it to generate documentation for our customized version. It also needs a configuration file, which is different from the one used for compiling. The default JSDoc configuration file can also be found in the config folder (config/jsdoc/api/conf.json). First, let's create a documentation with the default configuration file. For this, type the following command into the terminal:

node node_modules/jsdoc-fork/jsdoc.js -c config/jsdoc/api/conf.json

If you wait for the program to be completed, you will notice that there is a new folder in the directory, called out. This is the default output directory for JSDoc. If you open index.html inside this folder, you will see the generated API documentation with the ol.Ellispoid constructor and its vincentyDistance method:

Customizing the documentation

We can tell from the first API documentation export that JSDoc uses the same headers, just like Closure. However, it uses a different syntax in the configuration file and command line. Now, we customize the documentation template a little bit, starting with a few simple steps. First, let's add a little description to the ol.Ellipsoid constructor in ellipsoid.js:

/**
 * @classdesc
 * Class to create an ellipsoid to measure accurate geodesic distances,
 * where accuracy is more important, than performance.
 *
 * To create the WGS84 ellipsoid:
 *
 * ```js
 * var ellipsoid = new ol.Ellipsoid(6378137, 1 / 298.257223563);
 * ```
 *
 * @constructor
 * @param {number} a Major radius.
 * @param {number} flattening Flattening.
 * @api
 */

With the @classdesc tag, we can write an extensive class description for a symbol. The content marked by this tag gets a different class name in the generated documentation, and, thus, it can be distinguished from other descriptions with the help of CSS. With a special syntax, we can also embed a code snippet, which is not only displayed as a code in the documentation but also syntax that's highlighted based on the language we define.

Next, we modify the default template of OpenLayers 3. The library uses a modified version of the Jaguar template (https://github.com/davidshimjs/jaguarjs/tree/master/docs/templates/jaguar). First, we navigate to the template in the source code (config/jsdoc/api/template). In this folder, there are two folders of interest. First, let's navigate to the tmpl folder, which contains the skeleton of various parts of the API documentation. The main template is called layout.tmpl, which is our main target. When you open that template, you will see that there are two main parts in the body of the skeleton. The first one describes the navigation bar, while the second one is for the content. The horizontal navigation bar is a custom OpenLayers 3 feature; therefore, we remove it. To also add something to the documentation, we add an attribute footer with a timestamp:

<body>
    <div id="wrap" class="clearfix">
        <?js= this.partial('navigation.tmpl', this) ?>
        <div class="main">
            <h1 class="page-title" data-filename="<?js= filename ?>"><?js= title ?></h1>
            <?js= content ?>
            <footer>
                Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc <?js= env.version.number ?></a> on <?js= (new Date()) ?>
            </footer>
        </div>
    </div>
    <script>prettyPrint();</script>
    <script src="scripts/linenumber.js"></script>
    <script src="scripts/main.js"></script>
</body>

Tip

As these documents are just templates, you can call JavaScript variables and methods in them. Just use the right syntax (<?js= for an opening tag and ?> for a closing tag).

Now, we've gotten rid of the horizontal navigation bar, but we also lost the name of the application. Without a horizontal navigation bar, the best fixed place to put such an annotation is in the vertical navigation bar. To do this, we have to modify navigation.tmpl a little bit:

<div class="navigation">
    <p class="applicationName"><a href="index.html"><?js= env.conf.templates.applicationName ?></a></p>
    <div class="search">
        <input id="search" type="text" class="form-control input-sm" placeholder="Search Documentation">
    </div>
    […]

With this extension, our application's name, which is read out from the configuration file and stored in the env.conf.templates.applicationName variable at the time of being generated, will always appear on the top of the vertical navigation bar.

If we'd like to generate our modified API documentation now, we would notice that everything is working nice, aside from the white space in the place of the horizontal navigation bar. As both of the navigation bars are in a fixed position, the body of the document has a padding of 50px. This way, the horizontal navigation bar fits nicely at the top of the documentation. To fix this, we have to modify one of the template's CSS files. This can be found in the other folder of interest under the static/styles/jaguar.css path. In this CSS file, we only have to remove the padding from the body element:

body {
  padding-top: 50px;
}

Finally, before generating the new API documentation, let's change the configuration file a little bit. Most of the options are good to go; we only need to change the name of the application and the outputSourceFiles parameter. If this parameter is set to true, the source files get bundled along with the documentation and will be accessible from the corresponding symbol. The configuration file that we modify is located in the parent of the template folder (config/jsdoc/api/conf.json from the source code's root directory):

{
    […]
    "templates": {
        […]
        "default": {
            "outputSourceFiles": true
        },
        "applicationName": "OL3 with Ellipsoid"
    },

Now, at last, we run JSDoc again. This time, we specify another parameter: the output directory. We can do this with the -d argument. Don't forget to run this command from the source code's root directory:

node node_modules/jsdoc-fork/jsdoc.js -c config/jsdoc/api/conf.json -d apidoc

If we wait for the program to finish and look at the newly created apidoc folder, we can take a look at our new documentation:

The new API documentation is customized with a class description added to the ol.Ellipsoid constructor, and there is a source code page associated with every class. This is very nice; however, if we check the size of this new, extended documentation, it's the double of the one without the source code included. It seems like linking everything to the appropriate GitHub source file is a good practice.

Tip

Curious about the long, ugly, and partially broken links? The OpenLayers 3 API documentation tries to link every source to the appropriate GitHub source file. Take a look at config/jsdoc/api/template/static/scripts/main.js to discover and, optionally, modify/turn off this feature.

Previous Chapter

Extending OpenLayers 3

Next Chapter

Summary

Table of Contents for Mastering OpenLayers 3

Creating rich documentation with JSDoc

Customizing the documentation

Tip

Tip

Table of Contents for
Mastering OpenLayers 3