.d.ts emit drops JSDoc when generating overload signatures from JSDoc @overload

[aduth]

Bug Report

🔎 Search Terms

• overload
• jsdoc

🕗 Version & Regression Information

5.0.2

• I was unable to test this on prior versions because this is newly introduced in 5.0

⏯ Playground Link

Broken JavaScript/JSDoc version (see missing comment documentation in .d.ts output):

For comparison, see working TypeScript version (see included comment documentation in .d.ts output):

This snippet of code was adapted from the announcement post description.

💻 Code

// @ts-check

/**
 * Function description.
 * 
 * @overload
 * @param {string} value Param value description.
 * @return {void} Return value description.
 */

/**
 * Function description.
 * 
 * @overload
 * @param {number} value Param value description.
 * @param {number} [maximumFractionDigits] Param maximumFractionDigits description.
 * @return {void} Return value description.
 */

/**
 * Function description.
 * 
 * @param {string | number} value Param value description.
 * @param {number} [maximumFractionDigits] Param maximumFractionDigits description.
 */
function printValue(value, maximumFractionDigits) {
  // ...
}

🙁 Actual behavior

There are no docblock comments in generated .d.ts.

Screenshot from broken JavaScript/JSDoc code snippet:

🙂 Expected behavior

Generated .d.ts includes docblock comment descriptions for function, parameters, and return value of overloaded forms.

Screenshot from working TypeScript playground link above:

[fatcerberus]

Just letting you know, you swapped the expected and actual behavior (but not the corresponding screenshots, oddly).

[aduth]

Just letting you know, you swapped the expected and actual behavior (but not the corresponding screenshots, oddly).

Thanks! I updated the original text.

[sandersn]

This is most likely because @overload doesn't use the normal jsdoc host rules [1], so the common JSDoc code path in the .d.ts emitter won't work. But it might be some other oversight in .d.ts emit.

[1] In the example, there are 3 separate jsdoc comments before printValue. Every tag besides @overload only applies when it's the jsdoc comment right before its function. But the syntax of @overload requires separate comments to disambiguate the end of overload signatures and the beginning of the implementation signature.