coddoc (original) (raw)

Description

coddoc is a jsdoc parsing library. Coddoc is different in that it is easily extensible by allowing users to add tag and code parsers through the use of coddoc.addTagHandler and coddoc.addCodeHandler. coddoc also parses source code to be used in APIs.

Coddoc also supports the generation of markdown and html through the use of different templates. Currently the templates use Handlebars but you may use any templating engine you wish

JSDOC Tags

JSDoc tags currently supported are:

augments|extends : extend an object
lends : document all members of an anonymous object as members of a declared symbol
namespace : document a namespace
parameter|param|arg|argument : parameters of a function
return|returns : return value of a function
memberof|memberOf : explicitly document a cod block as a member of an object
name : explicitly document the name of a symbol
constructor|constructs : document a symbol as a constructor for a class
class : documents a symbol as a class
classdesc : alternate way to add a description to a class
example : document an example/s of a symbol
private : document a symbol as private.
ignore : allows you to document a symbol but ignore it in parsing
method|function : explicily document a symbol as a method
field : explicily document a symbol as a field
type : document the type of a field
default : document the default value of a field
throws|throw|exception : document any exception thrown by a method
property : document a property in the constructor declaration of a class
borrows : document any filed/methods borrowed from a class
constant|const : document a field as a constant
desc|description : alternate way to explicitly document the description of a symbol
public:explicitly document a symbol as public

Coddoc Tags

Coddoc also has a few additional tags.

ignoreCode : ignore the parsed code in the output
includeDoc : include an external doc. External docs can be html or markdown. Example
@includeDoc [Title Of Doc] ../location/of_doc.md
projectName : document the projectName
github : url to github project
code : specifies a code block without needing an example tag Example
{@code var test = "test"; }
header : allows you to document a header that should appear before generated documentation
footer : allows you to document a footer that should come after the generated documentation
protected : allows you to document a field as protected

Installation

Locally

npm install coddoc

Globally

npm install -g coddoc

Usage

Down doc does not currently create multi file docs instead will output to a single file. You may however implement your own formatter to create multiple files. Command line options

-d --directory : the directory that contains your code
[-f --formatter] : optional formatter to use, if not specified then a JSON object of the symbols will be output
[-p --pattern] : optional file pattern to use when searching for files

Examples JSON output

coddoc -d ./lib > symbols.json

To use the markdown formatter

coddoc -d ./lib -f markdown > README.md

To use the HTML formatter

coddoc -d ./lib -f html > index.html

To use pragmatically

var coddoc = require("coddoc"); var tree = coddoc.parse({directory : __dirname + "/lib"}); var classes = tree.classes, namespaces = tree.namespaces; //do something

API

License

MIT LICENSE