Readme.tpl

# 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.
```javascript
<%= alias %>
```

## Quick Start
```javascript
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:
```coffeescript
###*
 * 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](http://usejsdoc.org/)

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
<%= api %>

## Parser Module
<%= parser %>

#### Parsed Comment Object
```javascript
{   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
```javascript
{   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](https://lodash.com/docs#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.
```javascript
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
<%= parserAPI %>

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

#### Rule for coffee parser
```javascript
<%= coffeeRule %>
```

### License
MIT