dracupidnodoc
A simple and 'low-level' source code comments parser and documentation generator.
Oops, this doc is generated by nodoc itself !
Supported Languages
- CoffeeScript
Other languagage, especially javascript, will be supported soon.
Language Name Aliases
Use lower case, used both for language option and extname recognization.
{
"coffee": "coffee",
"coffeescript": "coffee",
"js": "javascript",
"javascript": "javascript"
}
Usage
Convert comment block to an object as following:
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, @option, @return name: 'srcPath', // only @param, @property, @option description: 'Path of source code file' }Tags are only key-value pairs, except
@param,@return,@property,@option. They may have extra type and (maybe) name.var doc = require('nodoc'); // From file doc.parser.parseFile('./src/parser/index.coffee').then(function(res){}); res = doc.parser.parseFileSync('./src/parser/index.coffee') //From source code doc.parser.parse('A piece of source code', 'coffee').then(function(res){});Generate gitHub flavored markdown API doc from comments.
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); });In this case, predefined tags will make effects.
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 name.@noPrefix: Only preserve the real name, regardutil.promisifyaspromisify.
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
API
generate (srcPath, opts) (alias: render)
Generate formatted markdown API document from source code
param:
srcPath{ string }Path of the source code file
param:
opts{ Object= }Options
{ 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 markdown
example:
nodoc.generate('./src/index.coffee').then(function(md){ console.log(md); });
parser
Parser module, see below for details.
Parser Module
parser.setParser (name, parser)
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 (source, language, opts)
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 (filePath, opts = {})
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: { Array }
parsed comment object array
parser.setRule (language, rule)
Set parser's rule
param:
language{ string }parser's name/language
param:
rule{ Object }parser's rule object
example:
nodoc.parser.setRule('coffee', { commentReg: /#?([\s\S]+?)#\s+([\w\.]+)/g });
Write your own template
Nodoc uses underscore 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 and register it by parser.setParser. 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 (source, localRule)
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 (ruleObj)
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.
Rules for coffee parser
{ commentReg: /###\*([\s\S]+?)###\s+([\w\.@'"]+)/g,
splitReg: /^\s+\* ?@/m,
tagNameReg: /^([\w\.]+)\s*/,
typeReg: /^\{(.+|}?)\}\s*/,
nameReg: /^([\w\.]+)\s*/,
nameTags: [ 'param', 'property', 'option' ],
descriptionReg: /^([\s\S]*)/,
removePrefix: /self\.|this\.|@|'|"/g }
License
MIT