jsdoc - jsdoc - 为多个功能重用文档?
问题描述
我有一个包含大量选项的函数:
/**
* Show dialog in a blocking manner.
*
* @param {object} opts
* @param {string} opts.msg "Body" of the dialog.
* @param {number} opts.timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* @param {string} opts.title Title of the dialog.
* @param {number} opts.icon Use constants for this. (See docs)
* @param {number} opts.buttons Use constants for this. (See docs)
* @param {number} opts.defaultButton Use constants for this. (See docs)
* @returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {
...
}
但我也有这个函数的非阻塞版本,显然采用相同的选项并返回一个 Promise。复制/粘贴文档似乎很脏,因为这会降低可维护性和意外不一致的可能性。
所以很棒的是如下所示:
/**
* Shows dialog in a non-blocking manner.
*
* @inheritdoc showSync
* @returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {
...
}
这有可能吗?
[更新]
这不是重复使用 Function 接口的 JSDoc的副本,因为这个问题只是关于重用相同的定义,而这个问题是关于重用但也部分覆盖了该定义。因此,那里的答案并没有回答这里的问题。
解决方案
我认为用 jsdoc 做到这一点的最好方法是这样的:
/**
* Options for showing a dialog.
* @typedef {Object} ShowOptions
* @property {string} msg "Body" of the dialog.
* @property {number} timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* @property {string} title Title of the dialog.
* @property {number} icon Use constants for this. (See docs)
* @property {number} buttons Use constants for this. (See docs)
* @property {number} defaultButton Use constants for this. (See docs)
*/
/**
* Show dialog in a blocking manner.
*
* @param {ShowOptions} opts
* @returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* @param {ShowOptions} opts
* @returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {...}
您可以更进一步,也可以将类似的概念应用于返回值:
/**
* Use our constants to check for what the user chose.
* @typedef {number} ShowResult
*/
/**
* Show dialog in a blocking manner.
*
* @param {ShowOptions} opts
* @returns {ShowResult}
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* @param {ShowOptions} opts
* @returns {Promise<ShowResult>}
*/
const show = (opts) => {...}
推荐阅读
- python - Python USACO 青铜级算法题:逻辑在理论上是合理的,但不知道如何实现
- c# - 除了它所针对的框架之外,其他框架是否支持 C# 语言版本?
- javascript - 如何在 LimberGridView 的左下角获取调整大小助手?
- c# - Rx.NET 中是否存在功能类似于 BehaviorSubject 但仅在值发生更改时才发出的 Subject 实现?
- xcode - Xcode 在禁用的代码行上触发断点
- flutter - 永远不会调用 ChangeNotifierProxyProvider 创建函数
- angular - 打字稿将计算值添加到类
- javascript - 如何使用 Javascript 自动滚动 ReactJS 项目类
- java - 如何将两个不同集合中的两个字段相乘
- c# - C#如何将两种数据类型合并到一个列表中