doctor

doctor

Doctor is still under development, so be careful.

Doctor converts JavaScript source to documentation, using rules to rely on conventions so that comment tags are (mostly) not needed.

Say what?

Maybe a picture will help:

Okay, maybe that needs some explanation.

Source files are parsed using a JavaScript grammar. This pushes out a plain Lisp-like AST. This is refined with some transform rules. The default transform rules also use a grammar to parse the JSDoc-style comment tags. This is to add in things that cannot be inferred from the JavaScript source, such as function description and parameter types.

Rules are applied to the refined AST to output a report, which is just a hash table of items and groups of items. The report is optionally run through a render module to convert the report to some format other than a single JSON file.

As a service, doctor also takes a number of view directories and merges them together into a single output directory, along with the report file(s). If the default single-file JSON is used, the view will be a JavaScript-based viewer that converts the report items into HTML.

Because of its modular and somewhat pluggable design, you can hack in your own grammars, rules, etc. and use it as a general-purpose AST analysis tool.

Installation

npm install doctor

or if you want the latest

npm install git:github.com/jdeal/doctor.git

Examples, please!

This is how doctor documents itself from the command-line:

doctor lib/*.js -v default -v doctor -o doc

You can see the documentation here.

Command-line usage

Dump a report file to the console:

doctor myfile1.js myfile2.js

To write out the report file, give it a directory:

doctor myfile1.js myfile2.js -o output

And it will write the report to a file named report.json. If you prefer a different name:

doctor myfile1.js myfile2.js -o output/myreport.json

You can also pass package.json files to doctor. It will use the main property to find the source file:

doctor package.json -o output

To output the default viewer along with your report:

doctor myfile1.js myfile2.js -o output -v default

To merge in your own files into the view, pass multiple views:

doctor myfile1.js myfile2.js -o output -v default -v ~/my-view

You can override the grammar if you feel adenturous:

doctor myfile1.js myfile2.js --grammar ~/my-better-grammar.pegjs

You can override the grammar for a specific file extension:

doctor myfile1.js myfile2.foo --grammar.foo foo

You can add your own transform rules:

doctor myfile1.js myfile2.js -t default -t ~/more-tranform-rules.js

Or your own report rules:

doctor myfile1.js myfile2.js -r default -r ~/more-report-rules.js

You can use a custom renderer:

doctor myfile1.js myfile2.js --render ~/my-render.js

Programmatic usage

All the same options are available programmatically.

var doctor = require('doctor');
var options = {
  files: ['myfile1.js', 'myfile2.js'],
  view: ['default', '~/my-view'],
  grammar: '~/my-better-grammar.pegjs',
  transform: ['default', '~/more-tranform-rules.js'],
  report: ['default', '~/more-report-rules.js'],
  render: 'markdown'
};
doctor.examine(options, function (err, report) {
  // done
});

Note that the above options probably don't really make sense. The default viewer doesn't work with output from the markdown renderer.