tomdox

JavaScript documentation generator for node using TomDoc

Tomdox is a simple JavaScript documentation generator that uses the excellent TomDoc notation, instead of the more verbose JSDoc.

It is inspired by dox, esdoc and biscoto and uses tomdoc package for the parsing (which was extracted from biscoto).

By default, it generates beautiful documentations using Material Design Lite, but can output raw JSON using the --json flag for more customisation.

Demo

• Usage
• API usage
• Documentation format
  • Method documentation
  • Visibility
  • Method arguments
  • Examples
  • Return types
• Templates
  • Themes
• JSON output
• Limitations

Usage

First install the package globally to make the tomdox command available on your system, or keep it in the devDependencies with --save-dev

# Global install
$ npm install tomdox -g

# Local install
$ npm install tomdox --save-dev

Running it with the -h flag:

tomdox files* [options]

Options:
  -t, --template    Path to a template directory with index.html / file.html
  -o, --output      Path to the destination directory (default: docs/)
  --primary         Primary color to use with the Material Design Lite template (default: blue_grey)
  --accent          Secondary color to use with the Material Design Lite template (default: orange)
  --icon            Optional material icon to use alongside title (See https://design.google.com/icons/)
  --json            Outputs JSON raw data to stdout
  --debug           Noop mode, nothing is written to disk
  --prefix          Prefix to use when generating URLs (default: /)

Examples

# Generates in docs/ from any JS files in working dir
$ tomdox

# Generates in api/ from any JS files in lib/
$ tomdox lib/**/*.js -o api/

# custom template (directory must include both index.html and file.html)
$ tomdox -t path/to/templates

# Change material design colors
$ tomdox --primary cyan --accent teal

API usage

var data = require('tomdox')(process.argv.slice(2), {
  output: 'docs/',
  primary: 'pink',
  accent: 'indigo',
  prefix: 'http://example.com/docs/'
});

// => data is the same as JSON outputs with --json flag

Documentation format

Originally designed for Ruby, TomDoc lends itself pretty nicely to JavaScript.

// Public: Duplicate some text an arbitrary number of times.
//
// text  - The String to be duplicated.
// count - The Number of times to duplicate the text.
//
// Examples
//
//   multiplex('Tom', 4)
//   # => 'TomTomTomTom'
//
// Returns the duplicated String.
function multiplex(text, count) {
  return new Array(count + 1).join(text);
}

Method documentation

https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#method-documentation

TomDoc for a specific method consists of a block of single comment markers (//) that appears directly above the method.

There SHOULD NOT be a blank line between the comment block and the method definition.

A TomDoc method block consists of six optional sections:

• a description section
• an arguments section
• an examples section
• a returns section
• a yields section
• a signature section

Sections MUST appear in the order listed above. Lines that contain text MUST be separated from the comment marker by a single space.

Note yields / signature section are more suited to Ruby, and tomdox doesn't handle them. Though, signature sections might make sense.

Visibility

Every class and method should start with one of three phrases: Public:, Internal:, and Private:, as described in the description section.

Right now, tomdox will only generate documentation for class & methods flaged as Public.

Method arguments

Each method argument must start with the argument name, followed by a dash (-), and the description of the argument:

argument - Some words about the arg!

Hash options are placed on a newline and begin with a colon:

options - These are the options:
          :key1 - Blah blah.
          :key2 - Blah

// Public: Complete constructor, accepts options hash with:
//
// options -  Accepts options hash (default: {})
//		:name - the String package name being completed, defaults to process.title
//						(if not node default) or will attempt to determine parent's
//						package.json location and extract the name from it
constructor(options) {
  super();
  this.options = options || this.defaults;

  if (!this.options.name) {
    this.resolveName();
  }

  this.handle();
}

Examples

The examples section must start with the word "Examples" on a line by itself.

The next line should be blank. The following lines should be indented by two spaces (three spaces from the initial comment marker) and contain code that shows how to call the method and optional examples of what it returns.

// Public: Complete class. This is the main API to interract with the
// completion system and extends EventEmitter.
//
// Examples
//
//   var complete = new Complete({
//     name: 'binary-name'
//   });
//
//   complete.on('list', function(data, done) {
//     return done(null, ['completion', 'result', 'here']);
//   });

Return types

When returning from a method, your line must start with the word Returns. You can list more than one Returns per method by separating each type on a different line.

The returns section should explain in plain sentences what is returned from the method. The line must begin with "Returns". If only a single thing is returned, state the nature and type of the value. For example:

// Returns the duplicated String.

If several different types may be returned, list all of them. For example:

// Returns the given String filepath or undefined if none was found.

Example

// Public: Duplicate some text an arbitrary number of times.
//
// text  - The String to be duplicated.
// count - The Number of times to duplicate the text.
//
// Returns the duplicated String.

Templates

Two Handlebars templates are used to generate HTML from the data object generated by tomdox.

The default behavior is to use the Material Design template located in the templates directory to render the documentation. This can be changed by using the template flag / option to specify a directory with an index.html and file.html files.

Each template is executed in the context of the documentation data, plus any other flag you may pass to the command line.

For instance, templates/index.html has both {{ title }} and {{ description }} placeholders, that you can override with:

$ tomdox --title Foobar --description "Totally awesome API"

If not defined, title and description are deduced from package.json file if it is present in the current working directory.

Themes

Material Design Lite comes with a smart and kinda powerfull color system.

Pick two colors that suit you and change the default options with:

$ tomdox --primary ping --accent indigo

Try out Material Palette to better decide which color combination you like the most.

Icon

Use --icon to generate a Material icon right next to the title.

JSON output

The json flag / options prevents the generation process and outputs the parsing result as JSON to stdout, like dox does. When the default template system is not enough, this provides more customisation.

Limitations

• As of now, comments must start with //. Block comments are not supported (/* ... */).
• As of now, only Public: type of visibility is generated, flags like --private and --internal should change the visibility output.
• Indentation must use space only. Tab indentations are not supported (but could be, just needs to adjust few regexp patterns)
• A few neat features from biscoto are yet to be implemented, notably the auto linking feature. I'd like to add autolinking to node builtin and core module