使用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) {
    // ...
}