JavaScript Documentation Style Guide

JavaScript Documentation

Table of Contents:

• General Guidelines
• JSdoc
• Global Variable Documentation
• Commenting

General Guidelines

All documentation must follow the following guidelines.

Declarative Voice

All documentation must be written in the declarative voice, e.g Constructs an Edge..

Periods

All documentation must end with a period.

Line Breaks

Documentation line length must be 80 characters or less.

The JSdoc

Every function must have a JSdoc. JSdocs sit atop the function declaration, and look like this:

/**
 * Constructs an Edge.
 * @param {Node} source This Edge's source Node.
 * @param {Node} target This Edge's target Node.
 * @param {string} id The id of the SVG path element that this 
                      Edge represents.
 * @constructor
 */
function Edge(source, target, id) {
    'use strict';

    this.source = source;
    this.target = target;
    this.id = id;
    this.status = 'inactive';
}

Types

@param and @return tags must have declared types. This improves readability, as JavaScript is both a dynamically and weakly typed language and often it is difficult to determine the type of a variable.

The different types are:

• {*} : Refers to anything/everything.
• {boolean}
• {string}
• {number}
• {object}
• {JSON}
• {Array} : Only use {Array} when the contents are unknown. Otherwise, use {content-type[]}, e.g. {string[]}.
• {Course}
• {Section}
• {Node}
• {Edge}
• {HTMLElement}
• {jQuery}

To use multiple types use the pipe character, e.g. {HTMLElement|jQuery}.

Every type must be surrounded with braces, e.g. { string }.

The type is put before the id, but after the tag, e.g. @param {string} name.

Tags

Here is a full list of usable JSdoc tags.

However, for our purposes we will only use a few. Additional tags can be appended at any time.

• @param - Used to define parameters.
• @return - Used to define a function's return value.
• @constructor - Used to indicate a constructor.

Global Variable Documentation

Commenting

Blank lines

Every single line comment must be preceded by a single blank line.