Generating and Viewing Custom Dojo API Documentation

By on January 18, 2013 12:30 am

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
    

  3. Edit environmentConfig object in config.js.
  4. 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.

  5. Parse like there’s no tomorrow.
  6. 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 
    $ 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.

  3. Move generated files.
  4. 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 
    $ 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.

Comments

  • Karl Bishop

    Nice introduction. The parsing of custom code is rather persnickety, and actually makes for a nice JSLint checker in its own right.

    One common doc parse error is:
    ERR: /{parh}/{to}/{Module}.js:164:24 TypeError: Cannot read property ‘1’ of null
    Caused by having a space between the argument and colon
    ex. (fsType : String, should be -> fsType: String)

  • dylanks

    I’m not sure I fully understand what you mean. That said, we find JSDoc style to be less robust and more verbose than the format we use for docs.

  • dylanks

    While I would consider anything, the jsdoc is not sufficiently flexible for the things we document in Dojo, and requires more boilerplate/redundancy than the format we created.

  • For the moment, use the wkeese fork, which is the one used to generate the official API docs. We’re trying to coalesce everything back down to a single repository eventually, but there are some higher-priority issues to be tackled first.

  • Daniel Mil, van

    What are the steps to run the parser.js with Rhino?

    Thanks.

  • There are no steps to run it on Rhino, since demand was never high enough for it. You’ll just have to use Node.js.

  • Daniel Mil, van

    from https://github.com/wkeese/js-doc-parse:

    “Works anywhere, not only on Rhino. (n.b. by “anywhere” I mean “node.js”, but there’s only a handful of code that needs to be abstracted for it to work on Rhino and in the browser, too, and I plan on doing just that.)”

    As this is not a plan anymore, any clues on what should be done to achieve this? We don’t want to include Node to our software requirements at this moment, so some (build) platforms that are used to generate jsdoc etc.can run more easily out of the Box on Rhino as we run on a Java backend (but Dojo frontend).

    I could spend some time on this task, so…

    Code looks like there was an attempt made (parser.js), but not finished.

    Thanks in advance!

  • Daniel Mil, van

    Dear Colin,

    Please ignore my questions about Rhino, not important anymore as we moved to nodejs also for future requirements.

    Another question: is it possible to run the parse-js-doc tool in Chrome in some way (ease of development, maybe some other use cases) as this also is described on the Wiki and some code browser code parts are present in the browser (node-webkit or …?) We’re planning on adding some jsdoc comments improvements to the code.

    Thanks in advance,

    Daniel van Mil.

  • bod.zak

    I suggest that the https://github.com/SitePen/js-doc-parse and https://github.com/csnover/js-doc-parse repositories are made private as it’s misleading to end users.