Docflux NPM | npm.io

docflux

Stream source code documentation block to json object

Features

Transform stream source code to docflux json object
Transform docflux json object to markdown
Support for multiline tag description

Api

Install the module with: npm install docflux

var docflux = require('docflux');

process.stdin(docflux())
  .on('data', function(jsdoc) {
    console.log(JSON.stringify(jsdoc, null, 2))
  })

Yield (see docflux json object below)

{"token": "MyClass#foo(a,b,[c])", "description": "...", "tags": [{...}]}
{"token": "MyClass#bar(a,b,[c])", "description": "...", "tags": [{...}]}

Command line tool

Install the command line tool with: npm install -g docflux

Usage: docflux docflux <file>

Options:

  -h, --help          output usage information
  -V, --version       output the version number
  -m --markdown       Output a markdown formated documentation (default to json)
  -o --output <file>  Output to this file
  -i --indent [size]  Indent json output
  -d --depth  <size>  Minimal header depth for markdown output

# Pipe to another json consumer
cat input.js | docflux | consumejson

# Use input and output
docflux input.js -o output.md

# Or write markdown output ...
docflux --markdown input.js > output.md

# Or write json output with indentation...
docflux input.js -i 4 > output.json

Supported comments style

Docflux support most of the jsdoc-like simple doc-block (see tests for more examples)

Short & compact doc-block style

/**
 * Create new user
 * Long description of this method
 * @param {String} name User name
 * @param {String|String[]} groupId Group id or array of group id
 * @param {Object} [options]
 * @returns {Boolean}
 */
 MyClass.prototype.createUser(name, groupId, options) { //...

Long doc-block style

/**
 * Create new user
 *
 * Long description of this method with list and examples
 *
 *   - Do this
 *   - And this
 *
 * Example:
 *
 *     var my = new MyClass();
 *     my.createUser('Foo',['admin','staff'], { silent: true });
 *
 * @param {String} name
 *        Username with some restrictions
 *        - Must be lower-case
 *        - Must be funny
 *
 * @param {String|String[]} groupId Group id or array of group id
 *        Put some markdow here too:
 *
 *            // Example
 *
 * @param {Object} [options]
 *   Options are always optional
 *   but params description alignement is based on first line indentation
 *
 * @returns {Boolean}
 *
 * @thows {InvalidUsernameException} Not funny (maybe)
 *
 * @see http://www.gelule.net/
 *
 * @memberOf MyClass
 */
      createUser: function(name, groupId, options) { //...

Output examples

docflux.markdown()

Opinionated stream that transform a docflux stream to markdown (see markdown output example) (nb: this is more a demo usage of docflux's json stream)

var docflux = require('docflux');

process.stdin(docflux())
  .pipe(docflux.markdown())
  .on('data', function(jsdoc) {
    console.log(JSON.stringify(jsdoc, null, 2))
  })

`@memberOf` tag

The @memberOf associate a backbone-like method with a class.

var MyClass = ClassCreator({
  /**
   * Create new user
   * @memberOf MyClass
   */
   createUser: function () { //...
})

Yield the following docflux.signature (with markdown transform):

## MyClass#createUser()

Add a dot to the memberOf tag (@memberOf MyClass.) to force a static method signature:

## MyClass.createUser()

docflux json object

For each jsdoc-style block in the source code, docflux provide a pojo javascript object with those fields:

token: The documented function or class or method
params: Formated parameters list (expl: a, b, [options])
memberOf: According to the @memberOf tag if present, the class of the currently documented method. Useful with backbone-like code (expl: MyClass)
signature: A formated signature (expl: MyClass#foo(a, b, [options]))
description: The full description part of the doc-block comment
summary: Only the summary part of the doc-block comment
body: The extended description part of the doc-block comment
tags: An array of tag object with:
- type: The tag name
- types: Array of types (for tags like @param {Object|String})
- token: The param token (for @param {Type} token)
- description: The full tag description
- summary: Only the summary part of the description (first line)
- body: The extended part of the tag description
- raw: The raw tag extracted from the doc-block comment
flags: An array of all tags name (type): can be used as flag to check a tag presence
isClass: True if this comment concern a Class (see isClass())
isFunction: True if this comment concern a function
isExports: True if this comment concern a module.exports
ignore: a @ignore tag exists
firstLine: The first line of code used to generated the token
raw: The full raw doc-block

Why another dox (and credit)?

Docflux was inspired by dox and dox is widely used with many other projects based on it: so consider using it if it match your needs
Docflux is a one-day project to provide
- A stream interface
- Less verbose and opinionated output (no pre-formated html output)
- Support for multiline tag description
Docflux output is partially compatible with dox output
Sometimes, reinventing the wheel opens new perspectives (sometimes not...)