The JvJsDoc Documentation Generator

By Jochen Voss, last updated 2012-11-15

Introduction

JvJsDoc is a program to extract documentation from JavaScript source code and to present the collected information in a set of HTML pages. It is meant to be used together with the Google Closure Library and the Google Closure Compiler. Features of JvJsDoc include the following:

Generates one HTML page with documentation per class/namespace.
A search box in the HTML output allows to quickly find the documentation for any given symbol.
Can optionally include the Closure Library documentation into the output to seamlessly document methods inherited from closure library-provided classes etc.
JvJsDoc is written in Python and requires Python version 3.2 or newer to run.

The development of JvJsDoc is still at an early stage, and there are still several known shortcomings of the program (e.g. inline JSDoc comments are not yet handled), but it works well enought that it is already useful for day-to-day work. Example output:

JvJsDoc-generated documentation for goog.Disposable can be found at m.seehuhn.de/data/jvjsdoc/example/.
For comparison, the official API documentation is on googlecode.com.

Please email any suggestions and bug reports to Jochen Voss. Your message should include the JvJsDoc version number, as obtained by the command jvjsdoc -V.

Download

You can download released versions of JvJsDoc from here:

jvjsdoc version 0.5, 2011-12-11

First public release.

archive: jvjsdoc-0.5.tar.gz (99KB)
signature: jvjsdoc-0.5.tar.gz.asc
sha1: 5e4f50a6fb941bd2fcfd9974cfddef89103779d4
md5: c2c837150df941fe17b4466516802724

More recent, experimental versions may (or may not) be found on github.com.

Installation

For installation of JvJsDoc you will need version 3.2 or newer of the Python interpreter installed. Optionally, to include documentation of Closure Library provided symbols in the generated output, the Closure Library JavaScript source needs to be available.

Generic installation instructions are in the file "INSTALL". On most systems, the following commands should be sufficient:

  ./configure
  make
  make install

If you get the error message no suitable Python interpreter found, this indicates that the configure script couldn't find a sufficently new version of Python. You can explicitly specify the location of the python interpreter to use, using the PYTHON configuration variable like this:

  ./configure PYTHON=/opt/local/bin/python3

If you have the Closure Library source code installed, you can configure JvJsDoc with the --with-closure-library option, to include the Closure Libary documentation:

  ./configure --with-closure-library=DIR

Here, DIR should be the directory which contains the closure/goog/deps.js file and the closure/bin/build/ directory. This configuration option enables the -g option of JvJsDoc.

Usage Without Installation

For easier experimenting, JvJsDoc can be used without installation. To do so, unpack the source somewhere and then run JsJsDoc as ./jvjsdoc.py from inside the source directory (note the trailing .py) in the command name. You may need to adjust the name of the python interpreter given in the first line of the ./jvjsdoc.py script in order for this to work.

JvJsDoc Usage

Information about all command line options can be found by running jvjsdoc -h. Basic usage is

  jvjsdoc -o htmldir jsdir1 jsdir2 ...

This recursively reads all javascript files found in the given directories jsdir1, jsdir2, … and extract all JSDoc tags. The tags are used to construct HTML files which are placed underneath the htmldir directory (which is created if necessary). A good starting point for the generated documentation is the output file htmldir/index.html.

If you configured JvJsDoc with the --with-closure-library option during installation, you can call the program as follows to include the Closure Library documentation in the output:

  jvjsdoc -g -o htmldir jsdir1 jsdir2 ...

References

The Google Closure Library
The Google Closure Compiler
The jsdoc-toolkit
The Google JavaScript Style Guide has advice on using JSDoc tags