Documenting

The project is using JSDoc3 documentation generator. The template is based on DocStrap. Learn the Use JSDoc resource for more information.

• Types
• Modules
• Constants
• Enumerations
• Functions
• Callbacks
• Structures
• Objects
• Events
• Deprecated

---

All public entities should be documented using special comments with appropriate tags. Complex methods or constructors should be supplied with code examples.

/**
 * Description.
 *
 * @tags
 *
 * @example
 * code
 */

We do not use the file-level documentation tags (@file, @author, etc).

Types

Following types are available:

• boolean
• number
• string
• Array
• Array.<MyObject>
• Object.<string, type> - dictionary
• function
• MyObject
• MyObject | null

Modules

/**
 * @namespace B.Module
 */
B.Module = {};

Constants

/**
 * Description.
 *
 * @constant
 * @type {number}
 * @default 128
 */
B.Module.CONSTANT = 128;

Enumerations

/**
 * Description.
 *
 * @enum {number}
 * @readonly
 */
B.Module.Enumeration = {

     /**
     * Description.
     *
     * @constant
     */
     CONSTANT = 1
};

Functions

/**
 * Description.
 *
 * @param {number} a description
 * @param {number} b description
 * @returns {boolean} description
 * @throws {B.Module.Error} description
 */
B.Module.myFunction = function (a, b) {

    // ...
};

If you use the function overloading, add @function tag with the object path to each declaration.

/**
 * Description.
 *
 * @function B.Module#myFunction
 * @param {number} val description
 */
/**
 * Description.
 *
 * @function B.Module#myFunction
 * @returns {number} description
 */
B.Module.myFunction = function (val) {

    // ...
};

Add @function tag for the closure + IIFE construction.

/**
 * Description.
 *
 * @function
 * @param {number} a description
 * @returns {boolean} description
 * @throws {Error} description
 */
B.Module.myFunction = (function() {

    var tempVariable = makeSome();

    return function (a) {

        // using temporary variable
    };
}());

Callbacks

/**
 * Description.
 *
 * @callback B.Module#callback
 * @param {number} a description
 * @param {number} b description
 * @returns {boolean} description
 */

/**
 * Description.
 *
 * @param {B.Module#callback} handler description
 */
B.Module.myFunction = function (handler) {

    // ...
};

Structures

/**
 * Description.
 *
 * @typedef B.Module#someParams
 * @type {Object}
 * @property {number} a description
 * @property {string} b description
 */

/**
 * Description.
 *
 * @param {B.Module#someParams} params description
 */
B.Module.myFunction = function (params) {

    // ...
};

Objects

/**
 * @ignore
 * @this B.Module.MyObject
 */
B.Module.MyObjectProto = function () {

    // ...
};

/**
 * Description.
 *
 * @class
 * @this B.Module.MyObject
 * @param {number} a description
 */
B.Module.MyObject = function (a) {

    /**
     * Description.
     *
     * @type {number}
     */
    this.someProp = a;
};

B.Module.MyObject.prototype = new B.Module.MyObjectProto();

The object inheritance pattern:

/**
 * @ignore
 * @this B.Module.Parent
 */
B.Module.ParentProto = function () {

    // ...
};

/**
 * Description.
 *
 * @class
 * @this B.Module.Parent
 */
B.Module.Parent = function () {

    // ...
};

B.Module.Parent.prototype = new B.Module.ParentProto();

/**
 * @ignore
 * @this B.Module.Child
 */
B.Module.ChildProto = function () {

    // ...
};

B.Module.ChildProto.prototype = B.Module.Parent.prototype;

/**
 * Desctiption.
 *
 * @class
 * @this B.Module.Child
 * @augments B.Module.Parent
 */
B.Module.Child = function () {

    B.Module.Parent.call(this);

    // ...
};

B.Module.Child.prototype = new B.Module.ChildProto();

The public API factory product pattern:

/**
 * Description.
 *
 * To create the object use [B.Module.makeProduct()]{@link B.Module#makeProduct}
 *  function.
 *
 * @class
 * @this B.Module.Product
 */
B.Module.Product = function (a, b, c) {

    // ...
};

Events

/**
 * Description.
 *
 * @event B.Module#myEvent
 * @type {B.Utils.Event}
 * @property {string} data.a description
 * @property {number} data.b description
 */

// listener's method:

    /**
     * Description.
     *
     * @fires B.Module#myEvent
     */
    this.myMethod = function () {

        this.trigger("myEvent", {
            a: "abc",
            b: 123
        });
    };

Deprecated

Use @deprecated tag for obsolete API.

/**
 * @deprecated description
 */