用jsdocloggingcallback的正确方法是什么？

我花了很长一段时间在互联网上寻找最好的方式来正确loggingjsdoc的callback，但不幸的是，我还没有find一个好的方法。

这是我的问题：

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

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

比方说，我定义了一个如下的函数：

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

使用jsdoc，我目前正在logging这个函数，如下所示：

 /** * 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); }); 

我觉得上面的解决scheme有点不好意思，因为我绝对不能指定callback函数应该接受的东西。

理想情况下，我想要做一些事情：

 /** * 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); }); 

上面的看起来似乎让我更简单地传达我的callback需要接受的东西。 那有意义吗？

我想我的问题很简单：什么是最好的方式清楚地logging我的callback函数与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

另一种可能性是通过这种方式来描述传递给callback函数的值：

 /** * 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); }); 

要loggingcallback的返回types，请使用@param {function(int):string} 。