When developing a JavaScript framework that others will consume, it’s hugely beneficial to provide clean, organized API documentation to accompany your codebase. With the August release of Dojo 1.8, we saw a brand new, extensible documentation parser, which is used to generate output for Dojo’s API viewer. Generating documentation for any project and serving up a custom API viewer is easy, and this post will show you exactly how to do it.

Dojo Markup Syntax

Any project wishing to take advantage of the API generation tools should comment their code using Dojo’s Inline Documentation syntax – a straightforward set of commenting conventions that allow for easy documentation parsing. This is analogous to Javadoc and other similar conventions used in most programming languages today. For example: 

// summary:
//            This is the summary for the method.
//            It's indented by two tabs.
// foo: Integer
//            First argument to this function
// bar: String
//            Second argument to this function
// returns:
//            A calculated value.

When parsing a comment block, the parser searches for a specific list of words or “keys”, including summary, description, this, and returns. Custom object properties and function parameters can also be documented using the same key-value comment format, as shown in the snippet above. Several other options are also supported, check out the full documentation for Dojo’s inline markup for more details.

Generating the docs

The Dojo team has worked hard to ensure that the actual generation of the docs was as simple as possible to configure and run. Before proceeding, make sure you have apache, node.js, and php 5.2 or greater installed. Next, it’s just three simple steps to generate shiny new API documentation:

  1. Clone js-doc-parse.

    2. $ git clone --recursive https://github.com/wkeese/js-doc-parse.git
$ cd js-doc-parse
$ git checkout all-my-changes

  2. Edit environmentConfig object in config.js.

    3. This tells the parser where your project is located. basePath should indicate the path to your project relative to config.js, and package paths should be relative to the basePath. 

    environmentConfig: {
    basePath: '../some/path/',
    packages: {
        myApp: 'myApp'
    }
}

    Note: other configuration options exist in config.js.

  3. Parse like there’s no tomorrow.

    4. The output will consist of the details.xml and tree.json files within the js-doc-parse folder.

    $ ./parse.sh ../some/path/myApp

That’s it! The documentation for your custom project has officially been generated. But how do we see it?

Viewing the docs

Now that the documentation has been successfully generated, all that’s left is to grab the API viewer in order to view the docs locally.

  1. Clone api-viewer.

    2. $ cd <web_server_root>
$ git clone git@github.com:wkeese/api-viewer.git api

    Note: If you want to put the API viewer in a location other than your server root, config.php and .htaccess need to be updated to point to the other location.

  2. Move generated files.

    3. We need to put the generated details.xml and tree.json in a location so the API viewer can find them. The viewer expects an api_data/ folder as its sibling with subfolders corresponding to project version numbers.

    $ cd <web_server_root>
$ mkdir api_data/
$ mkdir api_data/1.0
$ mv js-doc-parse/details.xml api_data/1.0/
$ mv js-doc-parse/tree.json api_data/1.0/
$ chmod -R +a 'user:_www allow delete,list,search,add_file,add_subdirectory,read,write' api_data

Finally, start your local Apache instance and point your browser to http://localhost/api/.

Theming the docs

Many users have asked how to modify the default theming of the API viewer itself. The styles and static content are broken down into a few key files that can easily be customized to fit your style needs, each of which will be included as the pages are generated.

  • theme.css – Includes any CSS styling that needs to be included in the document
  • index.php – Populates the Welcome tab of the API Viewer
  • header.php – Inserted before the main content area
  • footer.php – Inserted after the main content area

Conclusion

Rather than simply generating an endless page of formatted API documentation, Dojo’s documentation tools provide a clean, simple method to produce an enterprise-quality API viewer and documentation for any JavaScript project. While more advanced configuration options for generation and viewing are available, the above guide should get any project up and running with their very own API viewer.