jsdoc - 可以重复使用多个函数的文档吗？

Question

我有一个带有大量选项的函数：

/**
 * 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) => {
...
}

这是否可能以某种方式实现？

[更新]

这不是与 JSDoc for reused Function interface 重复，因为那个问题仅涉及重用相同的定义，而这个问题涉及重用但也部分重写该定义。因此，那里的答案无法回答这里的问题。

- AndyO

---

可能是JSDoc for reused Function interface的重复问题。 - Joshua Coady

@inheritdoc 对于普通类型也不起作用。它的文档说：“您在 JSDoc 注释中包含的任何其他标记都将被忽略。” - Joshua Coady

@JoshuaCoady 这就是我发出这个问题的原因。无论如何，感谢你的回答，对我来说看起来很不错。（不过我没有时间去确认它是否正确，因为我已经一年前转向了TypeScript。） - AndyO

Answer 1

我认为使用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) => {...}

- Joshua Coady