Question

我正在使用带有Google预设样式规则的JSCS来检查我的代码，并且我在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)函数范围内找到返回语句，但实际上它位于匿名回调(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作为唯一的参数。

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

1 个答案: