JSDoc Reference

[AndreGeng]

Getting started

JSDoc 3与javadoc和phpDocumentor类似, 是一个用于javascript的api文档生成器. 你可以在源代码中加入注释, JSDoc工具会扫描源代码并生成html文档. JSDoc的注释代码块以/**开头, 一般直接放在要注释的代码前面.

Block and inline tags

JSDoc支持两种tag, block/inline. Block类的标签提供代码的详细信息, 而inline类的标签则是对document其它部分的一个超链. inline类标签一般会包含{}, 例如{@link}, e.g.

/**
 * Set the shoe's color.
 *
 * @param {SHOE_COLORS} color - The shoe color. Must be an enumerated
 * value of {@link SHOE_COLORS}.
 */
Shoe.prototype.setColor = function(color) {
    // ...
};

Examples

ES 2015 Classes

/** Class representing a point. */
class Point {
    /**
     * Create a point.
     * @param {number} x - The x value.
     * @param {number} y - The y value.
     */
    constructor(x, y) {
        // ...
    }

    /**
     * Get the x value.
     * @return {number} The x value.
     */
    getX() {
        // ...
    }

    /**
     * Get the y value.
     * @return {number} The y value.
     */
    getY() {
        // ...
    }

    /**
     * Convert a string containing two comma-separated numbers into a point.
     * @param {string} str - The string containing two comma-separated numbers.
     * @return {Point} A Point object.
     */
    static fromString(str) {
        // ...
    }
}

Tags

@async

@callback

/**
 * @class
 */
function Requester() {}

/**
 * Send a request.
 * @param {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function(cb) {
    // code
};

/**
 * This callback is displayed as a global member.
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

@event & @fires & @listens

@event #[event:]

/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    /**
     * Snowball event.
     *
     * @event Hurl#snowball
     * @type {object}
     * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
     */
    this.emit('snowball', {
        isPacked: this._snowball.isPacked
    });
};

@example

/**
 * Solves equations of the form a * x = b
 * @example
 * // returns 2
 * globalNS.method1(5, 10);
 * @example
 * // returns 3
 * globalNS.method(5, 15);
 * @returns {Number} Returns the value of x for the equation.
 */
globalNS.method1 = function (a, b) {
    return b / a;
};

@external

/**
 * The built in string object.
 * @external String
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
 */

@global

(function() {
    /** @global */
    var foo = 'hello foo';

    this.foo = foo;
}).apply(window);

@implements & @interface

/**
 * Interface for classes that represent a color.
 *
 * @interface
 */
function Color() {}

/**
 * Get the color as an array of red, green, and blue values, represented as
 * decimal numbers between 0 and 1.
 *
 * @returns {Array<number>} An array containing the red, green, and blue values,
 * in that order.
 */
Color.prototype.rgb = function() {
    throw new Error('not implemented');
};

/**
 * Class representing a color with transparency information.
 *
 * @class
 * @implements {Color}
 */
function TransparentColor() {}

// inherits the documentation from `Color#rgb`
TransparentColor.prototype.rgb = function() {
    // ...
};

@mixin & @mixins

/**
 * This provides methods used for event handling. It's not meant to
 * be used directly.
 *
 * @mixin
 */
var Eventful = {
    /**
     * Register a handler function to be called whenever this event is fired.
     * @param {string} eventName - Name of the event.
     * @param {function(Object)} handler - The handler to call.
     */
    on: function(eventName, handler) {
        // code...
    },

    /**
     * Fire an event, causing all handlers for that event name to run.
     * @param {string} eventName - Name of the event.
     * @param {Object} eventData - The data provided to each handler.
     */
    fire: function(eventName, eventData) {
        // code...
    }
};

/**
 * @constructor FormButton
 * @mixes Eventful
 */
var FormButton = function() {
    // code...
};
FormButton.prototype.press = function() {
  this.fire('press', {});
}
mix(Eventful).into(FormButton.prototype);

@override

/**
 * @classdesc Abstract class representing a network connection.
 * @class
 */
function Connection() {}

/**
 * Open the connection.
 */
Connection.prototype.open = function() {
    // ...
};

/**
 * @classdesc Class representing a socket connection.
 * @class
 * @augments Connection
 */
function Socket() {}

/**
 * Open the socket.
 * @override
 */
Socket.prototype.open = function() {
    // ...
};

@param

1. Documenting a parameter's properties

   /**
   * Assign the project to an employee.
   * @param {Object} employee - The employee who is responsible for the project.
   * @param {string} employee.name - The name of the employee.
   * @param {string} employee.department - The employee's department.
   */
   Project.prototype.assign = function(employee) {
   // ...
   };

2. Documenting properties of values in an array

   /**
   * Assign the project to a list of employees.
   * @param {Object[]} employees - The employees who are responsible for the project.
   * @param {string} employees[].name - The name of an employee.
   * @param {string} employees[].department - The employee's department.
   */
   Project.prototype.assign = function(employees) {
   // ...
   };

3. An optional parameter and default value

   /**
   * @param {string} [somebody=John Doe] - Somebody's name.
   */
   function sayHello(somebody) {
   if (!somebody) {
       somebody = 'John Doe';
   }
   alert('Hello ' + somebody);
   }

4. Allows one type OR another type (type union)

   /**
   * @param {(string|string[])} [somebody=John Doe] - Somebody's name, or an array of names.
   */
   function sayHello(somebody) {
   if (!somebody) {
       somebody = 'John Doe';
   } else if (Array.isArray(somebody)) {
       somebody = somebody.join(', ');
   }
   alert('Hello ' + somebody);
   }

5. Parameters that accept a callback

   
   /**
   * This callback type is called `requestCallback` and is displayed as a global symbol.
   *
   * @callback requestCallback
   * @param {number} responseCode
   * @param {string} responseMessage
   */

/**

• Does something asynchronously and executes the callback on completion.
• @param {requestCallback} cb - The callback that handles the response. */ function doSomethingAsynchronously(cb) { // code };

  ## @private & @protected & @public

  /* @namespace / var Documents = { /**

  • An ordinary newspaper. */ Newspaper: 1, /**
  • My diary.
  • @private */ Diary: 2 };

    ## @property
    The @property tag is a way to easily document a list of static properties of a class, namespace or other object.

    /**

• @namespace
• @property {object} defaults - The default values for parties.
• @property {number} defaults.players - The default number of players.
• @property {string} defaults.level - The default level for the party.
• @property {object} defaults.treasure - The default treasure.
• @property {number} defaults.treasure.gold - How much gold the party starts with. */ var config = { defaults: { players: 1, level: 'beginner', treasure: { gold: 0 } } };

/**
 * User type definition
 * @typedef {Object} User
 * @property {string} email
 * @property {string} [nickName]
 */

@readonly

@requires

/**
 * This class requires the modules {@link module:xyzcorp/helper} and
 * {@link module:xyzcorp/helper.ShinyWidget#polish}.
 * @class
 * @requires module:xyzcorp/helper
 * @requires xyzcorp/helper.ShinyWidget#polish
 */
function Widgetizer() {}

@returns

Return value with multiple types

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @param {boolean} retArr If set to true, the function will return an array
 * @returns {(number|Array)} Sum of a and b or an array that contains a, b and the sum of a and b.
 */
function sum(a, b, retArr) {
    if (retArr) {
        return [a, b, a + b];
    }
    return a + b;
}

@see

/**
 * Both of these will link to the bar function.
 * @see {@link bar}
 * @see bar
 */
function foo() {}

// Use the inline {@link} tag to include a link within a free-form description.
/**
 * @see {@link foo} for further information.
 * @see {@link http://github.com|GitHub}
 */
function bar() {}

@since

/**
 * Provides access to user information.
 * @since 1.0.1
 */
function UserRecord() {}

@summary

用于写一个简短版本的描述

/**
 * A very long, verbose, wordy, long-winded, tedious, verbacious, tautological,
 * profuse, expansive, enthusiastic, redundant, flowery, eloquent, articulate,
 * loquacious, garrulous, chatty, extended, babbling description.
 * @summary A concise summary.
 */
function bloviate() {}

@this

用于指定方法内的this的指代

/** @constructor */
function Greeter(name) {
    setName.apply(this, name);
}

/** @this Greeter */
function setName(name) {
    /** document me */
    this.name = name;
}

@throw

标注方法可能抛出的异常.

/**
 * @throws {DivideByZero} Argument x must be non-zero.
 */
function baz(x) {}

@todo

@type

1. 多类型

   @type {(number|boolean)}

2. Array/Object

   @type {MyClass[]}
   @type {{a: number, b: string, c}}

3. 可为null的type

   @type {?number}

4. 不可为null的type

   @type {!number}

5. Variable number of that type

   @type {...number} num

typedef

/**
 * A number, or a string containing a number.
 * @typedef {(number|string)} NumberLike
 */

/**
 * Set the magic number.
 * @param {NumberLike} x - The magic number.
 */
function setMagicNumber(x) {
}

@yields

/**
 * Generate the Fibonacci sequence of numbers.
 *
 * @yields {number}
 */
function* fibonacci() {}

[AndreGeng]

Ref: jsdoc