Documentation Documentation

Standards

In general, any method should have a comment saying what it does, where it is called, etc. Any hacks should be well documented, with links to references.

Comments must be of a certain form in order for the browsable docs to be generated properly. Please follow the standards below.

Client-Side

Files

Required tags: @file, @author (at least one).

Each file should have a block at the top like the following:

/**
 *  @file       Widget.js
 *  @author     Colin Sullivan <colinsul [at] gmail.com>
 **/

A description of the file is not necessary because most of the time it will just contain a class of the same name.

If you are an author of this file, add another author line.

Classes

Required tags: @class, @extends (if this is a subclass), @scope (if using .extend, see below).

Each class should have a description, indicating what it is and where instances of it are used.

/**
 *  This contains general stuff that needs to take place for any widget on the UI.
 *	@class
 *  @extends    Backbone.View
 ...

If an instantiation of the class takes arguments, @param tags should be added just like any other function.

/**
 *  This contains general stuff that needs to take place for any widget on the UI.
 *	@class
 *  @extends    Backbone.View
 *
 *  @param  {jQuery tmpl object}    template    Template element for this widget
 *  @param  {Panel}                 panel       Panel containing this widget
 **/
 var Widget = Backbone.View.extend(
 ...

One more thing unfortunately, since we're typically using the _.extend method, the following @scope block must be included so the js-doc-toolkit knows that these are member functions:

var Widget = Backbone.View.extend(
	/**
	 *	@scope	Widget.prototype
	 **/
{
    ...

Functions

All functions should make use of the @param tag if any parameters are passed in. They should also all contain a description at the top that says what the function is doing.

var Widget = Backbone.View.extend(
	/**
	 *	@scope	Widget.prototype
	 **/
{
    /**
     *  Create the DOM elements associated with this widget using a template.  
     *  The widget is not inserted into the DOM in this class.  That is for whoever
     *  is instantiating the widget to take care of.
     **/    
    initialize: function() {
        ...

Member Variables

Anytime a member variable is saved to this, a comment should be used to describe the member variable:

initialize: function() {
    var params = this.options;

    var template = params.template;
    if(typeof(template) == 'undefined' && typeof(params.el) == 'undefined') {
        throw new Error('params.template or params.el must be undefined');
    }
    else if(typeof(template) != 'undefined' && template.length == 0) {
        throw new Error('template not found');
    }
    /**
     *  Template for this widget.
     **/
    this.template = template;

    var panel = params.panel;
    if(typeof(panel) == 'undefined') {
        throw new Error('params.panel is undefined');
    }
    /**
     *  The panel that this widget belongs to.
     **/
    this.panel = panel;
    ...

Following these standards will result in pretty pages like this:

Browsable Docs

The browsable documentation is generated in the gh-pages branch. You can browse the HTML documentation at concert.github.com/Concert/.

We are using Doxygen for Python documentation, and the [jsdoc-toolkit](http://code.google.com/p/jsdoc-toolkit/ "jsdoc-toolkit official site) for JavaScript.

How to Update Browsable Docs

There is a script in gh-pages called update.sh that will update code, generate the documentation, and then ask you to push the results to gh-pages. Currently, the script has my jsdoc-toolkit path hardcoded into the top of update.sh, so you need to change that if you want to generate the documentation yourself. Or you could just email me (colinsul [at] gmail.com) and i'll do it if you have pushed code that you'd like to see documented.