Skip to content

Create HTML Docs using JSDoc

Jump to bottom
Erik Neumann edited this page Apr 17, 2015 · 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