jsdoc - Reuse docs for multiple functions?

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.

Possible duplicate of [JSDoc for reused Function interface](https://stackoverflow.com/questions/55086068/jsdoc-for-reused-function-interface) — Joshua Coady, Nov 05 '19 at 05:37
`@inheritdoc` doesnt work that way for normal types either. Its docs say "Any other tags that you include in the JSDoc comment will be ignored." — Joshua Coady, Nov 11 '19 at 22:44
@JoshuaCoady Which is why I posted this question. Anyway, thanks for the answer, it looks good to me. (Don't have the time to actually confirm it myself though since I moved on to TypeScript about a year ago.) — AndyO, Nov 12 '19 at 13:14

score 5 · Accepted Answer · answered Nov 11 '19 at 22:45

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

jsdoc - Reuse docs for multiple functions?

1 Answers1