valid-jsdoc

此规则是 ESLint v5.10.0 中的 deprecated。

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 注释。它报告以下任何问题：

lcocvwWk9ihwoTWS+VM+Qk3cAOoQQHqrlGKeaIrvyyZCt8VI9mcOkOpM0+bHkd2CkQ9DnOU9+zCE1BggLH+bDcU/QQweuJGyX8HjpaLLm0UyUNur7x9rivDmaddeSzLSqIW73ryMrXYLeEoeIIO6zzMY7Pd7p7ou4iK3ur3U1/O5Ab4/WPA3CfG0gAyKxzF7gTt8VV0R/4TT0ZMVu+ec7/EIK9fjysz7zkx/7SXQyEdJnxcj9e36btDXVgJ9AQ4KP0caZfGfHDEpxBFtYij39erQ4bfmEiNeI5P12NJ11ZdFoITlxgmmBGGEoUNJOU/9KmYuxkclq1a3+zkohFlQxsefGljFwIDkAz9bRIPg69GoNZHfKsKMQFNjGX84sSHjQZgp3eACM7CkJeRl8J+eKEPo3ZOYVM4XxHr3Q05RKvdB7e5NtG4ZlSjjuBugzW1W4wUoBryyp6QsUGhQJBqqzg==

FwLlFTu3O0hWVkP4WDRQHXZ0rVV+mSSy70dOGYtUjS2OlHOoNKo8wwoSeSl9u1JoqsWFq8ra29aWVCDKtmKCBKBKc6r01LIIszASpLkX32k=

TOiIhAaba6b+oi13LOZui/zgv8yRNMfqaKv1RxD2/YRcvG9J0am/5ejvOx+vomtC1xQtLF5No1r3Fin7xVLylF0sDpou+K79MqYchcSGWlucy2twhqcQJe4wCnHNVQNpyG1OggUPFkPcZvuuy7upXOBFP7ICZzme7ssKphSVkvMmwV4/eQymMOgeGCL+aMcps6Z0DevGriHLxSijhTPTqKHgGOYWYkgduq4iVJravvQqoKNKoetsTyo9z8PMQpLnJSnSQwK/vIR7j+fy79iLFVRWlP9Nvq6e8Zt4Q0YFPoo+hahm2746IxrVMtOLNzY0RHO1n27TB03Er5ypKEntvSm4+0YYKp319Yn5n2Y5NPctXt2a/RcmE1pRNfq/kgWE8z+AuL5ZrEX2YSQkv8uJJ8wDi7sJh4QG2ztEG89p9GTIimJpMVVytQ5VW9FDic/BsnEyG5HTuafVNtiWQylgcpAeicfdTqq09gk9wEcVSNK5z+ZAuRuNS2QGUHbjq6YQ

hEQw+/5Ytu7qxMfTE9dfIO0XycuXctERMAtSu3Lug7r6kp0B/YPwvO18BFQVITrK

/*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;
}

YG27G4Pwk4piVfqau/3hfsKK46AV8vTF0CnlyXroG1g1maQoWbXq3/nLToSd4DSN

/*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
    }
}

选项

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

prefer

usUFST+XNaC0G4FBYCpW1u3q4QXubgkYXUp6pl47Hx88qIQtBAZQimvq1RoOL5zeTi/JUCRNc5vvCtbvMvzE66z0YNTmZQwhUODxTkB7ETAfARHC7azPvtAz0fT4NnVf/1+fQZZ1Jrajm1GeDphK0kw9YedEozEAUOb7yk3x7Wn0CZDoRJe4h2TlI2Y2vA2M7TXyGlN6cO7oYon7Hvup+fGQAKgfyz86dipkRsFGuZXUnDUiUTDtnYy3vN7Gi/lt1U9BGO/uIjmbBBZ9JMSZXQ==

/*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

usUFST+XNaC0G4FBYCpW1tjj29Bt7Itmj44YVYCKaozNqkBY5bLzqrBgoU6Ic20yt8Fvfobp68jIRPIkkUGfmzn+NRdHG383liO/kvi/2+UKYUjEq3tHTozBz1o20xItQQQAnQrILFpLuULpz+2hVv0UfkAOBHmvdpPN6wQ7mfT1NCwlwkneoTRAXQdXmRmsiPNMSoKkQzRGVMpZe5k03chKSOrQsQK7b4k4tFI8beY=

/*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

gZBkWoLrsruXbv0UeNk4YFIecmWgLesoC8VGbTjwwjuZyL+cCubxiKNzvWmZFLjGzh8XoiSaFdEeRkl57uTFlz9oGEKJkkz8i+7t76hcjgzNa7y44OtKEErqobyXCSur

/*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");
    }
}

gZBkWoLrsruXbv0UeNk4YFIecmWgLesoC8VGbTjwwjuZyL+cCubxiKNzvWmZFLjGzh8XoiSaFdEeRkl57uTFl4IQpwedTlV5FQqCV9jD7VZJB2ieuUiqmxlY5rSLByBG

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

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

requireReturnType

gZBkWoLrsruXbv0UeNk4YMKJH0Fe2BOEWsSNXPAA4VJyR1wbZ1PeH71UiJzwQCeTl7MsNQK98v51XLrnPuz20iblb/sNlgUEFf9rJ8ubyUQ87oc/9zBOhXGl5on1AnBH

/*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;
}

requireParamType

gZBkWoLrsruXbv0UeNk4YHqg3qTLNYcChK0jtyWyOoxRKSh+VA/SsthMphVw0AiympSl/30D1tJi2ByHqqHWThDeGAH4mg0MyuVysP9ZcVzeyC4lw8mU9JBV5JbuWCAo

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

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

matchDescription

usUFST+XNaC0G4FBYCpW1oDD6gIHmXIsG5JQNa+ZGiaN5h3axFsDrM6F/kOqx86D2eVwR9cbRJ1P6/rmKBLVQj0uLgz6D9ncvTIpqta0C/5GXLs+QL7BnmkVLOCaSW7KPeKANrSxoFx5gsmVDVMC+A==

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

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

requireParamDescription

gZBkWoLrsruXbv0UeNk4YA9Ml8jOIn7ODjzH2T9j8COGQTlAsSEdnEtJ/Rn5vKviGX2KHpKb80fQzUTWRzyb+Tpfp1dug7SPdsA9cVmCW7k/0TpaKuuxmkWdLKZxHF8kgjH7n0wEZdQqIh6Fqw8Ncw==

/*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

gZBkWoLrsruXbv0UeNk4YCt49ly06hjBvSNuARalF0nHEnvQLVNSzDa4cnSa+Myy7Y4GS5VVMiFE3OCP2rJVqX8wre0R47NR9Ja7wrrNRLKVvevWnJwTlLkwyiDIST9As6KVR06hQUbu4Vp5nl7dnQ==

/*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;
}

何时不使用

CnABFDlncE9IUM0M9/GjlCfzFDqFMdy/FRsA2Gd56OnnTthkt+iCcRih92JAlVnLff7xzR9hAuRiqxjQCWYh6iM3SwzBhPLuDr1xija/Fyk=