js创建html回调,javascript – 使用jsdoc记录回调的正确方法是什么？

我花了很多时间在搜索互联网寻找最好的方式来正确地记录回调与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的最好的方法？

感谢您的时间。