tomdox

> JavaScript documentation generator for node using [TomDoc][]

[TomDoc]: http://tomdoc.org/
[dox]: https://github.com/tj/dox
[esdoc]: https://github.com/esdoc/esdoco
[biscoto]: https://github.com/gjtorikian/biscotto
[tomdoc package]: https://www.npmjs.com/package/tomdoc
[Material Design Lite]: https://getmdl.io

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

---

$3

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

$3

``javascript
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
`

$3

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
[description]: https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#description
[arguments]: https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#arguments
[examples]: https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#examples
[returns]: https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#returns
[class/module]: https://github.com/mojombo/tomdoc/blob/master/tomdoc.md#class

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

`javascript
// 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.

`javascript
// 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:

`javascript
// Returns the duplicated String.
`

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

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

Example

`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.
//
// Returns the duplicated String.
`

$3

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.

$3

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.

$3

- 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