Rob Ferguson

Annotating JavaScript using JSDoc tags

Rob Ferguson -

JSDoc is a markup language used to annotate JavaScript, comments containing JSDoc tags can be used to produce HTML documentation and for declaring the type of a variable.

In this post we'll install JSDoc, look at some example markup and then generate some documentation.

Note: If you want to follow along then download and install the Vardyger publishing platform.

Install JSDoc

To install JSDoc, enter the following command:

npm install -g jsdoc

This will install JSDoc globally by placing modules in /usr/local/lib/node_modules:

and the executable file in /usr/local/bin.

Configure JSDoc

We've installed JSDoc globally, so to override the default configuration we need to place a file named conf.json in our working directory:

{
  "tags": {
    "allowUnknownTags": true
  },
  "source": {
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": [],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "default": {
        "outputSourceFiles": true
    }
  }
}

Note: JSDoc includes a sample configuration file named conf.json.EXAMPLE.

The Vardyger file structure:

├── /content
├── /core
    └── /client
    └── /server
        └── /api
            └── /controllers
                ├── posts.js
                ...
        └── /out [JSDoc output]
        ├── server.js
        ├── conf.json
        ...
    └── /shared

JSDoc Tags

I've already added some JSDoc tags to the posts.js controller:

/**
* findPostById
*
* returns a post in the Posts collection.
*
* @public
* @param {req} req - The HTTP request object.
* @param {res} res - The HTTP response object.
* @return {post} post - A post from the Posts collection.
* @see {@link http://expressjs.com/api.html#req}
* @see {@link http://expressjs.com/api.html#res}
*/

Now, we can try it out from the command line:

jsdoc ./api/controllers/posts.js

And, preview the generated HTML documentation in a browser:

You might also like to take a look at Docstrap and the JSDoc plugins for Grunt and Gulp.

References: