我已经花了相当长的时间在互联网上寻找可使用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);
});
我觉得上面的解决方案有点像黑客,因为我无法绝对地指定回调函数应该接受什么。
理想情况下,我想执行以下操作:
/**
* 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清楚地记录回调函数的最佳方法是什么?
感谢您的时间。