Nuclear Potato Monster

    docast

    0.1.1 • Public • Published

    DocAST

    Build Status

    DocAST is tool to help parse docs strings + additional properties from your javascript source code.

    Install

    NPM

    npm install docast

    git

    git clone git://github.com/brettlangdon/docast.git
    cd ./docast
    npm install

    CLI Usage

    From the command line you can use docast to pull comments out from javascript files and store into a json file or you can provide a javascript file to use to format the comments into some other form.

    Help Text

    $ docast --help
    Usage:
      docast (-h | --help)
      docast (-v | --version)
      docast extract [-o <output>] <input_files>...
      docast generate <formatter> <input_files>...
    
    Options:
      -h --help               Show this help text
      -v --version            Show docast version information
    Extract:
      Parse docs from javascript files and output as json to a file
      -o --output <output>    File to output to [default: out.json]
      <input_files>           List of javascript files to fetch docs from
    Generate:
      Provide a script used to generate documentation from the parsed docs
      <formatter>             Script which exports a `function(comments)` used to generate docs from comments
      <input_files>           List of javascript files to fetch docs from
    

    Extract

    $ docast extract -o out.json ./lib/*.js
    $ cat out.js
    [{"name":"func1","params":[],"returns":[],"raises":[],"doc":"this is func1"}, ...]
    

    Generate

    formatter.js

    // simply print the name of each function we have documentation for
    module.exports = function(comments){
        comments.forEach(function(comment){
            console.log(comment.name);
        });
    };

    Usage

    $ docast generate ./formatter.js ./lib/*.js
    func1
    func2
    

    Basic API Usage

    The below example shows how you can use DocAST to parse documentation data from your javascript source code.

    example.js

    /*
     * This function is super cool and does all sorts of cool stuffs
     */
    function some(cool, stuff){
        if(typeof cool === undefined || typeof stuff === undefined){
            throw new Exception('must provide "cool" or "stuff" parameter');
        }
     
        if(cool > stuff){
            return stuff;
        } else if(stuff > cool){
            return cool;
        } else {
            return null;
        };
    }

    Usage

    var docast = require('docast');
    var comments = docast.parse('./example.js');
    // this is the result
    comments = [ { name: 'some',
                   params: [ 'cool', 'stuff' ],
                   returns: [ 'stuff', 'cool', null ],
                   raises: [ 'Exception' ],
                   doc: ' This function is super cool and does all sorts of cool stuffs\n ' } ]

    Keywords

    none

    Install

    npm i docast

    DownloadsWeekly Downloads

    7

    Version

    0.1.1

    License

    MIT

    Last publish

    Collaborators

    • brett_langdon