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.

The JSdoc

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

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

    this.parent = parent;
    this.child = child;
    this.name = name;
    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:

• {string}
• {object}
• {number}
• {object}
• {Node}
• {Edge}
• {Course}
• {Section}
• The list will continue

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.