JavaScript注释规范

[wxforever]

使用jsdoc

github地址：https://github.com/jsdoc3/jsdoc 英文文档：http://usejsdoc.org/ 中文文档：https://www.css88.com/doc/jsdoc/index.html

常用注释

注释一个es6类

/** 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.
     * @example 
     * // returns 2
     * getX(5);
     * @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) {
        // ...
    }
}

注释一个es6模块

/** @module color/mixer */

/** The name of the module. */
export const name = 'mixer';

/** The most recent blended color. */
export var lastColor = null;

/**
 * Blend two colors together.
 * @param {String} color1 - The first color, in hexadecimal format.
 * @param {String} color2 - The second color, in hexadecimal format.
 * @return {String} The blended color.
 */
export function blend(color1, color2) {}

// convert color to array of RGB values (0-255)
function rgbify(color) {}

export {
    /**
     * Get the red, green, and blue values of a color.
     * @function
     * @param {String} color - A color, in hexadecimal format.
     * @returns {Array.<number>} An array of the red, green, and blue values,
     * each ranging from 0 to 255.
     */
    rgbify as toRgb
}

@param

/**
 * @param {String} [somebody=John Doe] - Somebody's name.缺省参数
 * @param {String} color - The second color, in hexadecimal format.
 */
function sayHello(somebody,color) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

其他标签

上面是最常用到到一些注释，其他还有很多注释形式，具体查看文档 http://usejsdoc.org/