Overview

Introduction

NJSDoc is a Documentation tool for JavaScript that works by executing code.

Tools like JSDoc try to parse source code. To make this work one has structure code and comments a certain way. Often this means things get specified twice, once in code and once in comments.

NJSDoc on the other hand evaluates the code using modified Rhino and stores the source code location of every assignment so it can calculate where each value comes from and which JSDoc comment is most appropriate. NJSDoc uses the prototype chain to classify objects as classes (constructors) and class members so it is compatible with many ad-hoc inheritance schemes.

Roadmap

Performance

The JQuery library can be processed in about 400ms. A large 70K LOC code-base with JSDoc comments can be processed in about 2.5 seconds.

Usage

usage: njsdoc [--list|--recipe] [--raw|--markdown|--html] [--out OUT] [--once] FILE
Generate JavaScript documentation by executing JavaScript code.
If --list is present then FILE is a list of paths to source files one per line.
If --recipe is present then FILE is interpreted as JavaScript defining recipes and hooks.
Otherwise FILE is a source file.
If --out OUT is present then output will go to this file, otherwise to stdout.
If --once is present then objects will be documented once even if present on both the protype and not.

Example

Get the latest version from the downloads section.

$ java -jar njsdoc-0.0.2.jar jquery-1.6.3.min.js --markdown >  jquery-1.6.3.min.md

Using the --recipe option

The recipe option allows one to programmatically build configuration using JavaScript.

$ java -jar njsdoc-0.0.4.jar --markdown --out out.md --recipe my-recipe.js

The following are examples of recipe definitions. Each expression is a recipe definition. In the example 'my-recipe.js' would contain exactly one recipe definition.

// Execute files in a specific order specified by a sequence file. Like --list.
//NJSDoc.defineSequence(<base path>, <list of paths, one per line>, [optional line filter regex]);
NJSDoc.defineSequence("src/", "otherProjectName/src/../files.lst");
NJSDoc.defineSequence("src/", "otherProjectName/src/../files.lst", "<script.*src=\"(.*)\\?");

// Advanced arbitrary recipe with files, sequence files and evaluated code
// file(), sequence(), and eval() can each be included zero or more times
NJSDoc.recipe("mobile web")
  .file("external/jquery.js") // relative file path
  .sequence("src/", "otherProjectName/src/../files.lst") // same as defineSequence() above
  .sequence("src/", "otherProjectName/application.hta", "<script.*src=\"(.*)\\?") // same as defineSequence() above
  .eval("var g = new MyGlobalObject()") // arbitrary expressions
  .define(); // complete the definition

// If execution order doesn't matter use modules()
NJSDoc.recipe("amd based library")
  .file("src/sys.js")
  .modules({path: "src/", exclude: ["src/end.js", "src/sys.js"]})
  .file("end/sys.js");

See Also