About

updoc converts special comments in your code into nice-looking documentation. You can document whatever information you want, and you can customize the output with templates.

Contribute on github

Examples

demo example.js creates example.html
boxbox uses updoc for its api documentation
bonus this site was created by this file

Getting Started

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:

/**
 * @secure true
 */
function multiply(a, b) {return a * b;}

This comment says that the function "multiply" has a property "secure" with the value "true". You can put whatever properties you want. The function name and parameters are detected and included in the documentation automatically.

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

Special Properties

Special updoc properties start with an underscore.

@_module is a special property for organizing your documentation.
@_depth overrides the module depth
@_name overrides the detected function or variable name
@_params overrides the detected parameter list
@_type overrides the detected type: 'function' 'var' or 'other'

properties with special formatting

The following properties aren't "special" but the default template displays them differently:

@header is used in the table of contents if no name is found
@description text is shown below other properties

updoc page properties

If an updoc comment contains any of these properties, that comment isn't output and instead defines information about the whole page.

@_page_title title for the whole page
@_page_description text shown under the title
@_page_css external css file to include
@_page_compact_index displays the deepest tier of your index inline instead of as list items
@_page_no_sort do not sort the output

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 contains the properties provided in the updoc comments, with a few bonus properties.

{
 version: '0.0.1', // updoc version
 title: 'updoc', // value of @_page_title
 ...
 sections: [ // each updoc comment is a section
  {
    _name: 'foo' // var name or function name
    _type: 'function', // function or var or other
    _params: 'x, y', // function parameters
    _module: 'example.util.foo', // full module name
    _depth: 3 // module nesting level
    awesome: 'extremely' // custom property
  }
 ]
}

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