使用 jsdoc 记录回调的正确方法是什么？

Question

我花了相当长的时间在互联网上寻找使用 jsdoc 正确记录回调的最佳方法，但不幸的是，我还没有找到一个很好的方法。

这是我的问题：

我正在为开发人员编写一个 Node.js 库。该库提供了开发人员将使用的多个类、函数和方法。

为了使我的代码清晰易懂，以及（希望）将来自动生成一些 API 文档，我开始在代码中使用 jsdoc 来自我记录正在发生的事情。

假设我定义了一个如下所示的函数：

function addStuff(x, y, callback) {
  callback(x+y);
});

使用jsdoc，我目前正在记录此函数，如下所示：

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

我觉得上面的解决方案有点hack-ish，因为我无法绝对指定回调函数应该接受什么。

理想情况下，我想做这样的事情：

/**
  * Add two numbers together, then pass the results to a callback function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {callback} callback - A callback to run.
  * @param {int} callback.sum - An integer.
  */
function addStuff(x, y, callback) {
  callback(x+y);
});

上面的内容似乎可以让我更简单地传达我的回调需要接受的内容。这有道理吗？

我想我的问题很简单：用 jsdoc 清楚地记录我的回调函数的最佳方法是什么？

感谢您的宝贵时间。

Answer 1

JSDoc 3 有一个 @callback 标签 正是为了这个目的。这是一个使用示例：

/**
 * Callback for adding two numbers.
 *
 * @callback addStuffCallback
 * @param {int} sum - An integer.
 */

/**
 * Add two numbers together, then pass the results to a callback function.
 *
 * @param {int} x - An integer.
 * @param {int} y - An integer.
 * @param {addStuffCallback} callback - A callback to run.
 */
function addStuff(x, y, callback) {
  callback(x+y);
}

Answer 2

另一种可能性是这样描述传递给回调的值：

/**
  * Add two numbers together, then pass the results to a callback          function.
  *
  * @function addStuff
  * @param {int} x - An integer.
  * @param {int} y - An integer.
  * @param {function(int)} callback - A callback to run whose signature is (sum), where
  *  sum is an integer.
  */
function addStuff(x, y, callback) {
    callback(x+y);
});

要记录回调的返回类型，请使用

@param {function(int):string}

。

Answer 3

@param {function(number):void} myCallback

自 2021 年起在 VS Code 和 WebStorm 中运行良好

Answer 4

让 VSCode 理解它的解决方法

/**
 * @typedef {function(FpsInfo)} fpsCallback
 * @callback fpsCallback
 * @param {FpsInfo} fps Fps info object
 */

 /**
 * @typedef {Object} FpsInfo
 * @property {number} fps The calculated frames per second
 * @property {number} jitter The absolute difference since the last calculated fps
 * @property {number} elapsed Milliseconds ellapsed since the last computation
 * @property {number} frames Number of frames since the last computation
 * @property {number} trigger Next computation will happen at this amount of frames
 */

/**
 * FPS Meter - Returns a function that is used to compute the framerate without the overhead of updating the DOM every frame.
 * @param {fpsCallback} callback Callback fired every time the FPS is computed
 * @param {number} [refreshRate=1] Refresh rate which the fps is computed and the callback is fired (0 to compute every frame, not recommended)
 * @returns {function} Returns a function that should be called on every the loop tick
 * @author Victor B - www.vitim.us - github.com/victornpb/fpsMeter
 */
function createFpsMeter(callback, refreshRate = 1) {
    // ...
}

Answer 5

可能我迟到了这个答案......但是这是我的贡献。使用 ES6 我们可以做到这一点：

    /**
 *
 * @param {import('../clients')} clients  
 */
export default function socketServer(clients) {
io.on('connection', (webClient) => {


    webClient.on('register', (data) => {
      clients.add(data, webClient);
    });
}

 server.listen(8081, function (err) {
    if (err) throw err;
    console.log('listening on port 8081');
  });

)

在“clients”文件夹中，我们有一个包含此代码的 index.js 文件

let clients = new Map();

/**
 * Add Client to Collection
 * @param {string} key
 * @param {object} client
 */
export function add(key, client) {
  clients.set(key, client);
}
/**
 * Remove Client from Collection
 * @param {string} key
 */
export function remove(key) {
  clients.delete(key);
}

export const size = () => clients.size;

因此，文件 /clients/index.js 中导出的所有函数都可以作为 JsDOC 使用，您可以通过 IntelliSense 引用它们

Answer 6

自此答案以来大约 10 年，Visual Studio 2022 v17.8.6 使用此代码可以正常工作（改编自该链接的答案）：

/**
 * Callback for adding two numbers.
 *
 * @callback addStuffCallback
 * @param {int} sum - An integer.
 * @returns {void}
 */

/**
 * Add two numbers together, then pass the results to a callback function.
 *
 * @param {int} x - An integer.
 * @param {int} y - An integer.
 * @param {addStuffCallback} callback - A callback to run.
 * @param {(x: int) => void} callback2 - A callback to run.
 */
function addStuff(x, y, callback, callback2) {
  callback(x + y);
  callback2(x + y);
}

注意：您可以使用 JSDoc

@callback

标记，如

addStuffCallback

所示（如果您打算为多个函数重用相同的回调签名，这很有用），但您也可以使用“内联”函数签名

@param {(x: int) => void} ...

，其中当您将鼠标悬停在函数上时，它的优点是可以在 Intellisense 中很好地显示

addStuff

: