[英]What's the proper way to document callbacks with 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 清楚地记录我的回调函数的最佳方法是什么?
感谢您的时间。
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);
}
另一种可能性是以这种方式描述传递给回调的值:
/**
* 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}
。
使 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) {
// ...
}
可能我迟到了这个答案......但是这是我的贡献。 使用 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 引用它们
@param {function(number):void}
截至 2021 年,在 VS Code 和 WebStorm 中运行良好
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.