jsdoc - Reuse docs for multiple functions? - jsdoc

Question

I have a function with a huge list of options:
/**
* 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) => {
...
}
But I also have a non-blocking version of this function obviously takes the same options and returns a Promise. It seems quite dirty to copy/paste the docs, as this will decrease maintainability and likelihood for accidental inconsistency.
So what would be great is something like the following:
/**
* 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) => {
...
}
Is this possible somehow?
[UPDATE]
This is not a duplicate of JSDoc for reused Function interface because that question is merely about reusing the same definition, while this one is about reusing but also partly overwriting that definition. And hence, the answer there does not answer the question here.

Answer 1

I think the best way to do that with jsdoc is something like this:
/**
* 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) => {...}
You could take it a step further and apply a similar concept to the return value as well:
/**
* 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) => {...}