Skip to content

Create HTML Docs using JSDoc

Jump to bottom
Michael Zhou edited this page Feb 12, 2016 · 5 revisions

How to create HTML documentation from a closure-compiler project by using the JSDoc tool:

The JSDoc project at http://usejsdoc.org is a kind of distant cousin to the closure-compiler project. Some recent (January 2015) changes to JSDoc have made it possible to use JSDoc on closure-compiler based projects. Specifically, the new JSDoc 3.3.0 version has better support for the @interface tag and inheritance among interfaces and classes, so that the @inheritDoc tag is correctly recognized.

Note that there are a couple of other projects aimed at generating docs for closure-compiler projects. See js-dossier and a discussion about closure docs.

Changes to Adapt to JSDoc

Here is a summary of changes needed to adapt a closure-compiler based project to work with JSDoc 3.3.0.

  • Add @classdesc to constructor of classes and interfaces. This is where to put the summary docs for the class or interface. Anything coming before the @classdesc will appear as the docs for the constructor itself.

  • Add @method to each method definition of an @interface. Not needed for methods defined in a regular (non-interface) class.

  • Add @implements as needed for classes/interfaces that inherit from another class/interface (JSDoc doesn't always infer this).

  • Add @static to static functions or properties.

  • To deal with goog.scope, use @alias to tell JSDoc what's happening. The @ignore tells JSDoc to not produce separate docs for the short-name variable. Here is the pattern:

goog.scope(function() {

  /**
   * @constructor
   */
  myproject.packageA.Foo = function() {
  };

  /**
   * @alias myproject.packageA.Foo
   * @ignore
   */
  var Foo = myproject.packageA.Foo;

  /**
   * @return {number}
   */
  Foo.prototype.makeBar = function() {
    return 0;
  };

}); // goog.scope
  • When compiling with closure compiler, add this compiler option:
--extra_annotation_name=alias

  • All types in @param and @return statements should be full path names. Don't use a goog.scope short-name there.

  • Specify "closure" in the tags.dictionaries config property. See http://usejsdoc.org/about-configuring-jsdoc.html. Here is a sample jsdoc_configure.json file showing this

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc","closure"]
  },
  "source": {
    "include": [
      "src/"
    ],
    "includePattern": ".+\\.js(doc)?$"
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": false,
    "default": {
      "outputSourceFiles": true,
      "layoutFile": "src/docs/layout.tmpl"
    }
  }
}

Current Problems Using JSDoc

As of April 2015 below are listed some problems of using JSDoc with closure-compiler. See the JSDoc issues list for more information.

Clone this wiki locally