nodoc

Generate gitHub flavored markdown API doc from source code comments.

Oops, this doc is generated by nodoc itself !

Supported Languages

• CoffeeScript

Other languagage, especially javascript, will be supported soon.

Language Name Alias

Use lower case, used both for language option and extname recognization.

{
    "coffee": "coffee",
    "coffeescript": "coffee",
    "js": "javascript",
    "javascript": "javascript"
}

Quick Start

var doc = require('nodoc'),
    fs = require('fs');

doc.generate('./src/parser/index.coffee', {
    moduleName: 'parser',
    moduleDesc: 'This is a parser!'
}).then(function(markdown){
    fs.writeFileSync('./api.md', markdown);
});

Comment format

Of course, you need to write your comments in a standard way to make a parser work. Such as:

###*
 * Generate formatted markdown API document from source code
 * @param  {string} srcPath Path of source code file
 * @param  {Object=} opts    Options, optional
 * @return {Promise}        Resolve formatted markdown
 * @example
 * ` ``javascript
 * nodoc.generate('./src/index.coffee').then(function(md){
 *     console.log(md);
 * });
 * ` ``
###

As you can see, you can use markdown in your comment!

Reference: jsdoc

More and more tags is going to be supported.

Predefined tags

• @private: Hidden in the generated document.
• @nodoc: Same behavior as @private, but they are differ in semantics.
• @alias: Shown as an addition of function name.
• @prefix: Add a custom prefix to function

API

• generate (alias: render )

  Generate formatted markdown API document from source code

  • param: srcPath { string }

    Path of source code file

  • param: opts { Object= }

    Options, optional

    {
        moduleName: '', // module name of the file, or it will be auto set to file name, of parent directory name for `index` file.
        moduleDesc: '', // module decription
        template: '',   // custom template
        tplData: {},    // addition template data
        cwd: process.cwd()   // current working directory
        language: ''         // specify the language, or it will be auto recognized by extname
        rule: {}                // specific parser rule, items vary from parsers
    }

  • return: { Promise }

    Resolve formatted markdown

  • example:

    nodoc.generate('./src/index.coffee').then(function(md){
        console.log(md);
    });

• parser

  Parser module, see below for details.

Parser Module

• parser.setParser

  Create a new parser or override an old ones

  • param: name { string|Array }

    parser's name/language (and aliases)

  • param: parser { Object }

    parser object, see below

• parser.parse

  Parse source code directly.

  • param: source { string }

    source code

  • param: language { string }

    specify source language

  • param: opts { Object= }

    option, optional

  • return: { Array }

    parsed comments object array

  • example:

    nodoc.parser.parse("This is source code with comments", "coffee").then(function(comments){
        console.log(comments);
    })

• parser.parseFile

  Parse source code from file. Use Promise instead of callback

  • param: filePath { string }

    souce file path

  • param: opts { Object= }

    options

  • return: { Promise }

    resolve parsed comment object array

  • example:

    nodoc.parser.parseFile("index.coffee", {cwd: './src'}).then(function(comments){
        console.log(comments);
    });

• parser.parseFileSync

  Synchronous version of parseFile

  • return: { Object }

    parsed comment object array

• parser.setRule

  Set parser's rule

  • param: language { string }

    parser's name/language

  • param: rule { Object }

    parser's rule object

  • example:

    nodec.parser.setRule('coffee', {
        commentReg: /#?([\s\S]+?)#\s+([\w\.]+)/g
    });

Parsed Comment Object

{   name: 'parseFile',
    description: 'Parse source code from file. Use Promise instead of callback',
    tags: [ [Object], [Object], [Object], [Object] ], // tag objects array
    lineNum: 78 
}

Tag Object

{   tagName: 'param',
    type: 'string', // only @param, @property, @return
    name: 'srcPath', // only @param, @property
    description: 'Path of source code file'
}

Write your own template

Nodoc uses Lo-Dash template to render the markdown template. You need to realize that template is not HTML's privilege.
If you don't want to use the default template, you can use your own.

doc.generate('./src/parser/index.coffee', {
    template: 'Here is your own template'
    tplData: {}  // You can use this object to add custom data to your template
}).then(function(markdown){});

However, if you even want to use a alternative template engine, please use parser module directly.

Write your own language parser

If the languages you use is not supported by nodoc, you can write your own parser. If you want your parser to be a part of nodoc, please make a pull request, it is warmly welcomed.

A parser should provide follow APIs:

Parser API

• parse

  Parse comment from source code

  • param: source { string }

    source code

  • param: localRule { Object= }

    optional, custom rule object, use once

  • return: { Array }

    parsed comments object array

• setRule

  Set the rule of the parser

  • param: ruleObj { Object }

    rule object

• getRule

  Hmm..., I'd like to use this to generate document.

  • return: { Object }

    rule object

Rule

A parser uses and is supposed to expose the rules it uses to parse the code.

Rule for coffee parser

{ commentReg: /###\*([\s\S]+?)###\s+([\w\.]+)/g,
  splitReg: /^\s+\* ?@/m,
  tagNameReg: /^([\w\.]+)\s*/,
  typeReg: /^\{(.+?)\}\s*/,
  nameReg: /^(\w+)\s*/,
  nameTags: [ 'param', 'property' ],
  descriptionReg: /^([\s\S]*)/ }

License

MIT