javascript - JavaScript 中匿名回调的冗余 JSDoc @return

Question

我使用 JSCS 和 Google 预设样式规则来检查我的代码，并且我在 DAO 类中有一个方法，定义如下:

/**
 * 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) => { ... }.

如何正确记录该返回语句？我的方法在某种程度上是错误的还是不好的？

Answer 1

add 不会返回任何内容，因此当 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 作为其唯一参数的回调。