Documenting JavaScript with jsdoc3


JavaScript is an extremely dynamic language which allows it to be applied in a variety of interesting ways. Some prefer to take the structured approach whilst others prefer an object-oriented approach using the prototype object or a library that offers a more classical approach. This diversity makes docblock type documentation seem impossible…but it isn’t!!

Thanks to jsdoc3 this task is made significantly simpler. It’s rich selection of tags makes it possible to document even the most abstract concepts that JavaScript permits. It is also extremely easy to create plugins and custom templates. Jsdoc is a command-line tool that works on any platform that supports Java. See project pages for information about usage.

Useful Links:

A Few Examples

Here are some examples of how jsdoc3 can be applied:

Function

/**
 * Do something really neat
 */
function foo() {
}

/**
  * Do something really neat with parameters - last is optional!
  * @param {string|number} lookup Name or ID of user
  * @param {string} type Type of records to lookup
  * @param {string} [count] Maximum count of entries to retrieve
  * @returns List of records
  */
function getRecords(lookup, type, count) {
}

Note that the other variant of functions can be documented in the same way:

/**
 * Do something really neat
 */
foo = function() {
};

Namespace

Straightforward namespaces can be documented with the following:

/**
 * Root namespace
 * @namespace root
 */
root = {
   /**
    * Do something really neat
    */
   foo: function() {
   }
};

/**
 * Nested namespace
 * @namespace root.nested
 */
root.nested = {
   /**
    * Do something else that is really neat
	*/
   bar: function() {
   }
};

Namespaces can still be documented when a more abstract mechanism is used. @lends allows members to be added to an existing namespace:

/**
 * Root namespace
 * @namespace root
 */
$namespace('root', /** @lends root **/ {
   /**
    * Do something really neat
    */
   foo: function() {
   }
});

/**
 * Nested namespace
 * @namespace root.nested
 */
$namespace('root.nested', /** @lends root.nested **/ {
   /**
    * Do something else that is really neat
    */
   bar: function() {
   }
});

Class (with prototype object)

/**
 * Base class of a game entity
 * @class Entity
 */
Entity = function() {
};

/**
 * Render entity
 * @param {CanvasRenderingContext2D} dc Device context
 */
Entity.prototype.render = function(dc) {
   // Instance method!
};

/**
 * Get new instance of entity
 * @param {string} type Type of entity to instantiate
 * @returns {@link Entity}
 */
Entity.getInstance: function(type) {
   // Static method!
};

Classes (with classical approach)

/**
 * Base class of a game entity
 * @class Entity
 */
$class('Entity', /** @lends Entity# **/ {
   /**
   * Render entity
   * @param {CanvasRenderingContext2D} dc Device context
   */
   render: function(dc) {
      // Instance method!
   }
}, /** @lends Entity **/ {
   /**
    * Get new instance of entity
    * @param {string} type Type of entity to instantiate
    * @returns {@link Entity}
    */
   getInstance: function(type) {
      // Static method!
   }
});
/**
 * Ball entity
 * @class Ball
 * @extends Entity
 */
$class('Ball', 'Entity', /** @lends Ball# **/ {
   /**
    * Force ball to bounce
    */
   bounce: function() {
      // Instance method!
   }
});
Advertisements

6 thoughts on “Documenting JavaScript with jsdoc3

    1. Thank you for your kind words!

      jQuery is a great tool, it makes things so much simpler. I was using PrototypeJS a while back, primarily because it provided a classical style classes for JavaScript. I will be releasing an open source project very soon which adds similar functionality that is compatible with jQuery.

      JavaScript could have even more of a purpose with Google’s V8 engine because it can be easily embedded into any C++ application. I can see a lot of potential for using JavaScript as an easy to grasp scripting language for a video game. It looks like the mapping between “hidden classes” in V8 and real classes in C++ is relatively straightforward. I don’t know if this is of interest to you but here is a link with an introductory video http://code.google.com/apis/v8/

      Best wishes

  1. I’m trying JsDoc3, but I’m stuck at the command line usage under windows:
    C:\workspace\jsdoc>java -jar lib/js.jar test\cases\alias.js
    doesn’t produce any output and the only command line usage note says:

    but –destination doesn’t work, and no ‘out’ folder is created…

    1. Hello Clausiobosticco!

      Okay I usually run jsdoc3 on my Mac but I believe that the following command should work (if you have jsdoc3 installed to C:\jsdoc3″:

      java -classpath C:\jsdoc3\lib\js.jar org.mozilla.javascript.tools.shell.Main -modules C:\jsdoc3\lib\node_modules -modules C:\jsdoc3\lib\rhino_modules -modules C:\jsdoc3\lib C:\jsdoc3\lib\jsdoc.js –dirname=C:\jsdoc3\lib

      Note: I am unable to test this at the moment, let me know how you get on!

      1. Hello Lea!

        thank you very much, with your help I succedeed.
        Here are the details if someone else need them

        this command line:
        F:\JsDoc3>java -classpath lib/js.jar org.mozilla.javascript.tools.shell.Main -modules node_modules -modules rhino_modules jsdoc.js -c conf.json -h
        printed out the Options

        and this:
        F:\JsDoc3>java -classpath lib/js.jar org.mozilla.javascript.tools.shell.Main -modules node_modules -modules rhino_modules jsdoc.js -c conf.json -r -d out test/cases/alias.js
        parsed F:\JsDoc3\test\cases\alias.js file and produced documentation in F:\JsDoc3\out folder

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s