1

我正在使用带有 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标记标记为冗余，因为它在函数范围内找不到 return 语句add(user)，但它实际上驻留在匿名回调(err, rows) => { ... }中。

如何正确记录该退货声明？我的方法在某种程度上是错误的还是坏的？

4

1 回答 1

0

add不返回任何内容，因此当 JSDoc 告诉您您的@return标签不合适时，它是正确的。如果您重构代码以便add接受传递结果的回调（如如何从异步调用返回响应中所述？），您最终会得到

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)。

如何记录这个？请参阅如何使用 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底部是独立的。它定义了一种回调函数，在这种情况下，它是一个接受 aUser作为其唯一参数的回调。

于 2016-03-24T17:52:06.747 回答