valid-jsdoc

JSDoc通过JavaScript代码中特殊格式的注释生成应用程序编程接口（API）文档。例如，这是一个函数的JSDoc注释：

/**
 * Add two numbers.
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 * @returns {number} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

如果由于输入错误而导致注释无效，则文档将不完整。

如果注释不一致，因为当函数定义被修改时它们没有被更新，那么读者可能会感到困惑。

规则细节

此规则强制执行有效且一致的JSDoc注释。它报告了以下任何问题：

• 缺少的参数标签：@arg，@argument或@param
• 与函数或方法相比，注释中参数名称的顺序不一致
• 缺少返回标记：@return或@returns
• 缺少参数或返回类型
• 缺少参数或退货说明
• 语法错误

此规则不报告类，函数或方法的缺少JSDoc注释。

注意：此规则不支持所有Google Closure文档工具的用例。因此，一些代码(/**number*/ n => n * 2);将被标记为缺少适当的函数JSDoc注释，即使/**number*/是一个类型提示而不是该函数的文档块。如果您以这种方式使用类型提示，我们不建议使用此规则。

此规则的错误代码示例：

/*eslint valid-jsdoc: "error"*/

// expected @param tag for parameter num1 but found num instead
// missing @param tag for parameter num2
// missing return type
/**
 * Add two numbers.
 * @param {number} num The first number.
 * @returns The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

// missing brace
// missing @returns tag
/**
 * @param {string name Whom to greet.
 */
function greet(name) {
    console.log("Hello " + name);
}

// missing parameter type for num1
// missing parameter description for num2
/**
 * Represents a sum.
 * @constructor
 * @param num1 The first number.
 * @param {number} num2
 */
function sum(num1, num2) {
    this.num1 = num1;
    this.num2 = num2;
}

此规则的正确代码示例：

/*eslint valid-jsdoc: "error"*/
/*eslint-env es6*/

/**
 * Add two numbers.
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 * @returns {number} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

// default options allow missing function description
// return type `void` means the function has no `return` statement
/**
 * @param {string} name Whom to greet.
 * @returns {void}
 */
function greet(name) {
    console.log("Hello " + name);
}

// @constructor tag allows missing @returns tag
/**
 * Represents a sum.
 * @constructor
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 */
function sum(num1, num2) {
    this.num1 = num1;
    this.num2 = num2;
}

// class constructor allows missing @returns tag
/**
 * Represents a sum.
 */
class Sum {
    /**
     * @param {number} num1 The first number.
     * @param {number} num2 The second number.
     */
    constructor(num1, num2) {
        this.num1 = num1;
        this.num2 = num2;
    }
}

// @abstract tag allows @returns tag without `return` statement
class Widget {
    /**
    * When the state changes, does it affect the rendered appearance?
    * @abstract
    * @param {Object} state The new state of the widget.
    * @returns {boolean} Is current appearance inconsistent with new state?
    */
    mustRender (state) {
        throw new Error("Widget subclass did not implement mustRender");
    }
}

// @override tag allows missing @param and @returns tags
class WonderfulWidget extends Widget {
    /**
     * @override
     */
    mustRender (state) {
        return state !== this.state; // shallow comparison
    }
}

选项

该规则有一个对象选项：

• "prefer"强制执行一致性文档标记，该标记由属性表示的对象指定而不是关键使用值（例如，"return": "returns"表示而不是@return使用@returns）
• "preferType"强制执行由属性表示的对象指定的一致的类型字符串，而不是键的使用值（例如，"object": "Object"表示而不是object使用Object）
• "requireReturn" 需要返回标签：
  • true（默认），即使函数或方法没有return语句（此选项值不适用于构造函数）
  • false 当且仅当该函数或方法有一个return语句（该选项值适用于构造函数）
• "requireReturnType": false 允许在返回标签中缺少类型
• "matchDescription"指定（作为字符串）正则表达式以匹配每个JSDoc注释中的描述（例如，".+"需要描述;此选项不适用于参数或返回标记中的描述）
• "requireParamDescription": false 允许在参数标签中缺少描述
• "requireReturnDescription": false 允许在返回标签中缺少描述

prefer

带有示例选项的此规则的其他不正确代码示例"prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" }：

/*eslint valid-jsdoc: ["error", { "prefer": { "arg": "param", "argument": "param", "class": "constructor", "return": "returns", "virtual": "abstract" } }]*/
/*eslint-env es6*/

/**
 * Add two numbers.
 * @arg {int} num1 The first number.
 * @arg {int} num2 The second number.
 * @return {int} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

/**
 * Represents a sum.
 * @class
 * @argument {number} num1 The first number.
 * @argument {number} num2 The second number.
 */
function sum(num1, num2) {
    this.num1 = num1;
    this.num2 = num2;
}

class Widget {
    /**
     * When the state changes, does it affect the rendered appearance?
     * @virtual
     * @argument {Object} state The new state of the widget.
     * @return {boolean} Is current appearance inconsistent with new state?
     */
    mustRender (state) {
        throw new Error("Widget subclass did not implement mustRender");
    }
}

preferType

带有示例选项的此规则的其他不正确代码示例"preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" }：

/*eslint valid-jsdoc: ["error", { "preferType": { "Boolean": "boolean", "Number": "number", "object": "Object", "String": "string" } }]*/
/*eslint-env es6*/

/**
 * Add two numbers.
 * @param {Number} num1 The first number.
 * @param {Number} num2 The second number.
 * @returns {Number} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

/**
 * Output a greeting as a side effect.
 * @param {String} name Whom to greet.
 * @returns {void}
 */
function greet(name) {
    console.log("Hello " + name);
}

class Widget {
    /**
     * When the state changes, does it affect the rendered appearance?
     * @abstract
     * @param {object} state The new state of the widget.
     * @returns {Boolean} Is current appearance inconsistent with new state?
     */
    mustRender (state) {
        throw new Error("Widget subclass did not implement mustRender");
    }
}

requireReturn

此规则的附加错误代码示例包含以下"requireReturn": false选项：

/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/

// unexpected @returns tag because function has no `return` statement
/**
 * @param {string} name Whom to greet.
 * @returns {string} The greeting.
 */
function greet(name) {
    console.log("Hello " + name);
}

// add @abstract tag to allow @returns tag without `return` statement
class Widget {
    /**
     * When the state changes, does it affect the rendered appearance?
     * @param {Object} state The new state of the widget.
     * @returns {boolean} Is current appearance inconsistent with new state?
     */
    mustRender (state) {
        throw new Error("Widget subclass did not implement mustRender");
    }
}

此规则的附加正确代码示例包含以下"requireReturn": false选项：

/*eslint valid-jsdoc: ["error", { "requireReturn": false }]*/

/**
 * @param {string} name Whom to greet.
 */
function greet(name) {
    console.log("Hello " + name);
}

requireReturnType

此规则的附加正确代码示例包含以下"requireReturnType": false选项：

/*eslint valid-jsdoc: ["error", { "requireReturnType": false }]*/

/**
 * Add two numbers.
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 * @returns The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

matchDescription

带有示例选项的此规则的其他不正确代码示例"matchDescription": ".+"：

/*eslint valid-jsdoc: ["error", { "matchDescription": ".+" }]*/

// missing function description
/**
 * @param {string} name Whom to greet.
 * @returns {void}
 */
function greet(name) {
    console.log("Hello " + name);
}

requireParamDescription

此规则的附加正确代码示例包含以下"requireParamDescription": false选项：

/*eslint valid-jsdoc: ["error", { "requireParamDescription": false }]*/

/**
 * Add two numbers.
 * @param {int} num1
 * @param {int} num2
 * @returns {int} The sum of the two numbers.
 */
function add(num1, num2) {
    return num1 + num2;
}

requireReturnDescription

此规则的附加正确代码示例包含以下"requireReturnDescription": false选项：

/*eslint valid-jsdoc: ["error", { "requireReturnDescription": false }]*/

/**
 * Add two numbers.
 * @param {number} num1 The first number.
 * @param {number} num2 The second number.
 * @returns {number}
 */
function add(num1, num2) {
    return num1 + num2;
}

何时不使用

如果你不使用JSDoc，那么你可以安全地关闭这个规则。

进一步阅读

• JSDoc

相关规则

• require-jsdoc

版本

这条规则是在ESLint 0.4.0中引入的。

资源

• Rule source
• Documentation source