1.1.2 • Public • Published

docflux Build Status NPM version

Stream source code documentation block to json object



Install the module with: npm install docflux

var docflux = require('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>
  -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
# Or write markdown output ... 
docflux --markdown input.js >
# 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
 * @memberOf MyClass
      createUser: function(name, groupId, options) { //...

Output examples


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');
  .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...)


The MIT license (see

Package Sidebar


npm i docflux

Weekly Downloads






Last publish


  • jponchon