README

Block Flow

Yet another documentation generator. This one, however, uses custom annotations to place emphasis on event-driven/streaming APIs. It also exposes your API data as an API. That's so meta.

Install

blockflow is available as a command line tool or as a module which you can leverage from within your own code base. To install the cli

[sudo] npm install -g blockflow

To install as an importable module

npm install blockflow --save

/**
 * @listener aSocketEventListener
 * @topic foo
 * @description get's called when client sends data
 * @callbackArg fooObj
 */
socket.on('foo', function(fooObj){

});

/**
 * @broadcaster something
 * @topic something
 * @snippet
 * {
 *   some: 'data'
 * }
 * @endsnippet
 */
socket.broadcast('something', { some: 'data' } );

CLI Usage

blockflow -s path/to/src

The above generates the documentation in the default directory. The docs generated are very wireframey and should probably be styled according to your liking.

Alt text

To learn more about available options read below or just type the command itself with no options

blockflow

Module Usage

var blockflow = require( 'blockflow' );
var opts = {
  verbose: true
};

blockflow

  .from( '/path/to/src' )

  // returns an event emitter
  .flow( opts )

    // fired everytime a block is parsed and available...a "flow" of blocks :)
    .on('block', function( block ){

    })

    // fired when all blocks have been parsed
    // callback returns all blocks (in case you weren't listening)
    // in an array
    .on('end', function( srcRoot, allBlocks ){

    })

API Mode

An API for your API

blockflow -s /path/to/src -a -p 8080 -e /docs

The above command will parse your docs, create a JSON object and expose it via a RESTful endpoint at http://localhost:8080/docs

Still very alpha-ish at the moment. More docs and features coming soon.

Options

Option	Flag	Required	Default	Desciption
Source	-s	Yes	N/A	The root of your source tree
out	-o	No	./blockflow_docs	Web output directory.
API Mode	-a	No	fasle	Expose raw block data at a RESTful endpoint
Endpoint	-e	No	/blockflow	The endpoint at which to expose raw block data
Port	-p	No	9000	Port for the API mode server
Verbose	-v	No	false	Use verbose logging

Usage no npm install needed!