About

updoc lets you document your code however you want. You provide the information you care about, then updoc generates nice-looking documentation for it. You can customize the output using templates.

It's suitable both for internal developer documentation and external api documentation.

Features

flexible so you can use it however you want
aware of function names, var names, and modules
templates are easy to create and modify
html allowed in comments
json output if you want it

Example

demo example.js creates example.html
bonus this site was created by this file

Contribute

on github

Using updoc

First install node and npm if you don't have them. Then install updoc like this: sudo npm install updoc -g Use updoc like this: updoc input.js output.html An optional 3rd argument specifies the template.
In your JavaScript code, put comments that look like this:

/**
 * @param x value to be returned
 * @foobar a property I made up
 */
function bat(x) {return x;}

You can put whatever properties you want. There are a couple special ones:

@module is a special property for organizing your documentation.
@name overrides the detected function or variable name
@type overrides the detected type: 'function' 'var' or 'other'
@depth overrides the module depth

That's all the special properties. However, the default template displays these two properties differently:

@header formats the entire section like a header. can be blank or contain a string
@description this text is shown with a lighter background below other properties

Rules

start updoc comments with /** on new line
close updoc comments with */ on new line
leading *s are stripped
@ indicates a property (escape with @)
lines following a property are included in that property
text before any properties is not documented

Modules

updoc sorts and nests your documentation by modules. Each updoc comment can have a @module property. It looks like this: @module app.util The function or var name is automatically added to the end of the module if appropriate. For example:

/**
 * @module foo.bar
 */
function bat() {} // my module is foo.bar.bat
 
var dog = {
   /**
    * @module dog
    */
   bark: function() {} // my module is dog.bark
};

Code of this form has its module set automatically: foo.bar.bat = function() {} // my module is foo.bar.bat However, for now, updoc doesn't try to guess modules in this case: this.bar = function() {} // my module isn't detected Also, the window object isn't included in your module: window.bar.bat = function() {} // my module is bar.bat Modules are only automatically detected in the line after an updoc comment. There isn't a full semantic awareness of your code, just a static analysis of one line per comment.
If the module property is omitted and isn't detected you get a top-level section.

Templates

updoc currently uses underscore templates.

Templates consume a json file. This json file is just the properties provided in the updoc comments, with a few bonus properties.

{
 version: '0.0.1', // updoc version
 sections: [ // each updoc comment is a section
  {
    name: 'foo' // var name or function name. may be absent
    type: 'function', // function or var or other
    prop: 'val', // @prop val
    module: 'example.util.foo', // @module example.util
    depth: 3 // module depth. @module foo is depth 1
  }
 ]
}

You can view the raw json output by specifying "json" as the output file

Highlighting

The default template uses prettify. To get code highlighting, just put prettify.js and prettify.css in the same directory as your output. Then put code in a code element like this: <code>function() {}</code>

Created by Greg Smith at Bocoup