jsdoc - 为多个功能重用文档？答案

【问题标题】：jsdoc - Reuse docs for multiple functions?jsdoc - 为多个功能重用文档？
【发布时间】：2018-12-10 15:14:47
【问题描述】：

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

/**
 * 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 的重复，因为这个问题只是关于重用相同的定义，而这个问题是关于重用但也部分覆盖了该定义。因此，那里的答案并没有回答这里的问题。

【问题讨论】：

JSDoc for reused Function interface的可能重复
@inheritdoc 也不适用于普通类型。它的文档说“您在 JSDoc 注释中包含的任何其他标签都将被忽略。”
@JoshuaCoady 这就是我发布这个问题的原因。不管怎样，谢谢你的回答，我觉得很好。（自从我大约一年前转向 TypeScript 以来，没有时间亲自确认这一点。）

标签： jsdoc jsdoc3

【解决方案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) => {...}

【讨论】：