jsdoc.md

Some docs I made for contributing documentation:

Using JS Doc

Any comments written with a comment block /** comment block **/ will get picked up by jsdoc. If you have comments you would like to make that don't show up in the documentation, use // comment.

Namespace docs are created by putting /** @namespace */ before the variable. Each key can be documented with a comment block that is broken down like this:

/**
 * Brief description of the method
 * @param {number} n number of things
 * @param {string} propName - Some long description of what this does
 * that really is too complex to represent on one line (when it is
 * better to be specific than terse)
 * @returns {type}
 */

Type can be string, object, integer, number, boolean, or even a class. Primitive types are boolean, number, string. The values undefined and null are also considered primitive. These are always lowercase. Object types are Objects including Arrays and Functions and are written uppercase.

Example:

 /** @namespace */
    var util = {
        /**
         * Repeat <tt>str</tt> several times.
         * @param {string} str The string to repeat.
         * @param {number} [times=1] How many times to repeat the string.
         * @returns {string}
         */
        repeat: function(str, times) {
            if (times === undefined || times < 1) {
                times = 1;
            }
            return new Array(times+1).join(str);
        }
    };

Defining a Class

Before the function that sets up the class add a code block that contains @class or @constructor.

Example:

/**
 * Represents a Primitive.
 * @constructor
 * @param {string} value description
 * @property {string} name 
 */
function Primitive(value) {
  this._name = value;
  model.primitive(this._id=++id, this);
  return this;
}

/**
 * Returns the primitive name
 * @returns {string}
 */
Primitive.prototype.getName = function(){
  return this._name;
}

Setting it up this way makes it compile with all the class methods on the same page.

If you compile and for some reason a method ends up under global, you can force it to be under a class by using @memberof Class or @memberof! Class. The ! is similar to using an !important tag in css.

If a class extends another class, you can document that with @extends Class.

You can chose to document private and public variables using @private and @public. With our conventions, private variables will be referenced with an underscore. eg: this._foo = secrets;.

Linking to vendor documentation

If you are using a vendor library and would like to link to their documentation use @link:

/**
 * Returns a Number between -π and π representing the angle theta between this Point
 * and another Point
 * Uses {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2|atan2}.
 * @param {Point} point The point to provide angle from.
 * @return {Number} Angle of Point.
 */
Point.prototype.angleToPoint = function(point) {
  return Math.atan2(point.y - this.y, point.x - this.x);
};