The JvJsDoc Documentation Generator

By Jochen Voss, last updated 2012-11-15

Contents

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:

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:

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.

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

Copyright © 2012, Jochen Voss. All content on this website (including text, pictures, and any other original works), unless otherwise noted, is licensed under a Creative Commons Attribution-Share Alike 3.0 License.