/README.md

# Introduction #



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



Tools like [JSDoc](https://github.com/jsdoc3/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](https://bitbucket.org/nexj/rhino-njsdoc) 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 #



* IDE integration to generate content assist for libraries - see: [https://bitbucket.org/nexj/webtools.jsdt.core](https://bitbucket.org/nexj/webtools.jsdt.core)

* Prettier output that looks more like traditional JSDoc

* Plugin system to support AMD and other module systems 



# 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 #



* Modified Rhino required by NJSDoc: [https://bitbucket.org/nexj/rhino-njsdoc](https://bitbucket.org/nexj/rhino-njsdoc)

* Eclipse plugin exposing NJSDoc API: [https://bitbucket.org/nexj/njsdoc-build](https://bitbucket.org/nexj/njsdoc-build)

* Fork of the Eclipse Javascript editor JSDT using NJSDoc: [https://bitbucket.org/nexj/webtools.jsdt.core/src/njsdoc](https://bitbucket.org/nexj/webtools.jsdt.core/src/njsdoc)