来自 JavaScript 中匿名回调的冗余 JSDoc @return

Question

我正在使用带有 Google 预设样式规则的 JSCS 来检查我的代码，我在 DAO class 中有一个方法定义如下：

/**
 * Inserts a new user into database.
 *
 * @param {User} user User to insert.
 * @return {User} Last inserted user.  // Redundant return statement
 * @throws Error if query fails.
 * @since 1.0
 */
add(user) {
  this.pool.getConnection((err, conn) => {
    conn.query('INSERT INTO users SET ?', user, (err, rows) => {
      if (err) {
        throw err;
      }
      conn.release();
      return this.getById(rows.insertId);
    });
  });
}

JSCS 将 JSDoc @return 标记标记为冗余，因为它在 add(user) 函数范围内找不到 return 语句，但它实际上驻留在匿名回调中 (err, rows) => { ... }.

如何正确记录 return 语句？我的方法在某些方面是错误的还是不好的？

Answer 1

add 不会 return 任何东西，所以当 JSDoc 告诉您您的 @return 标签不合适时，它是正确的。如果您重构代码以便 add 接受传递结果的回调（如 How do I return the response from an asynchronous call? 中所述），您最终会得到

add(user, resultCallback) {
  this.pool.getConnection((err, conn) => {
    conn.query('INSERT INTO users SET ?', user, (err, rows) => {
      if (err) {
        throw err;
      }
      conn.release();
      resultCallback(this.getById(rows.insertId));
    });
  });
}

用 add(user, result => { ... }) 代替 result = add(user) 来调用它。

如何记录这个？请参阅 How to document callbacks using JSDoc? 它看起来像：

/**
 * Inserts a new user into database.
 *
 * @param {User} user User to insert.
 * @param {userResultCallback} resultCallback callback with last inserted user
 * @throws Error if query fails.
 * @since 1.0
*/
add(user, resultCallback) {
  //...
}

/**
 * Callback used to get a single User value.
 * @callback userResultCallback
 * @param {User} user Result of the callback
 */

最下面的@callback是单机的。它定义了一种回调函数，在本例中是一个接受 User 作为其唯一参数的回调。

来自 JavaScript 中匿名回调的冗余 JSDoc @return

Redundant JSDoc @return from an anonymous callback in JavaScript

javascript

callback

jsdoc

jscs