JavaScript Documentation Style Guide

#JavaScript Documentation Table of Contents:

• JSdoc
• Global Variables
• Commenting

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';
}

Declarative Voice

JSdoc descriptions must be written in the declarative voice, e.g Constructs an Edge..

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.

Punctuation

Every description in a JSdoc must end with a period.

Global Variable Documentation

Commenting

Declarative Voice

As with global variables and JSdocs, the declarative voice must be used here as well.

Blank lines

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