JS Doc comment not shown in signature help when overload tag exists

[ITenthusiasm]

🔎 Search Terms

overload jsdoc

🕗 Version & Regression Information

Because @overload was introduced in TS 5.0, I don't think this is a regression. It may just be something that was missed when overloads were introduced.

⏯ Playground Link

💻 Code

/* -------------------- Distinct Docs -------------------- */
/**
 * Do something with number
 * @overload
 * @param {number} a
 * @returns {void}
 */

/**
 * Stringing
 * @overload
 * @param {string} a
 * @returns {void}
 */

/**
 * @param {string | number} a
 * @returns {void}
 */
function doSomething(a) {}

doSomething(1);
doSomething("");

Also See

/* -------------------- Fallthrough -------------------- */
/**
 * This does something different
 * @overload
 * @param {boolean} b
 * @returns {void}
 */

/**
 * @overload
 * @param {object} b
 * @returns {void}
 */

/**
 * @param {boolean | object} b
 * @returns {void}
 */
function doSomethingDifferent(b) {}

doSomethingDifferent(true);
doSomethingDifferent({});

/* -------------------- Deferred Fallthrough -------------------- */
/**
 * @overload
 * @param {Event} c
 * @returns {void}
 */

/**
 * Only Mutation Observers do cool things
 * @overload
 * @param {MutationObserver} c
 * @returns {void}
 */

/**
 * @param {MutationObserver | Event} c
 * @returns {void}
 */
function anotherThing(c) {}

anotherThing(new Event("click"));
anotherThing(new MutationObserver(() => {}));

🙁 Actual behavior

The types resulting from the JSDocs are correct, but the comments are lost. This same issue occurs for overloaded constructors.

🙂 Expected behavior

As is the case for regular overloads in TypeScript (example), I would expect my JSDoc comments that use the @overload tag to be preserved.

[RyanCavanaugh]

to be preserved.

To be preserved where?

[ITenthusiasm]

That's a great question. The JSDoc comments (/** ... */) are definitely moved over to the .d.ts file during compilation. So in a sense, they are "preserved". But the documentation doesn't seem to be preserved in the IDE. That is, if I call my function, overloaded(), in VS Code, I don't see the documentation for that function. I mainly just see type information. This problem only occurs when using the @overload approach in .js files; using regular overloads in .ts files works fine. So I'm not sure whether it's a VS Code issue, or an issue with how TypeScript is communicating documentation information.

But I suppose more accurately, I would like for the documentation information to be preserved in VS Code?

IDE (VS Code) Info for .ts Files (Universal)

If I define an overloaded function, overloaded, in functions.ts and write JSDoc comments for the function and its parameters, then when I call the function or hover it, I get the correct documentation.

/**
 * You can count on me
 * @param a NUMBER
 * @param b BOOLEAN
 */
function overloaded(a: number, b: boolean): void;
/**
 * Does some string stuff
 * @param a STRING
 * @param b OBJECT
 */
function overloaded(a: string, b: object): void;
function overloaded(a: string | number, b: boolean | object): void {
  //
}

When I start typing out overloaded in VS Code, I see the entire JSDoc information for the first overload. This means I see the comments for the function, and the comments for the parameters. As I start providing parameters, the parameter documentation for the current parameter moves to the top, and the documentation for the function moves to the bottom. Docs for parameters that I'm not currently supplying disappear because they are irrelevant.

If I type overloaded() and starting pressing ArrowDown/ArrowUp, I can toggle between the different overloads and the documentation for the params/function body.

If I hover overloaded (after providing proper arguments), then I get the entire JSDoc information for the overload.

These experiences remain consistent even after TypeScript compiles the .ts file.

IDE (VS Code) Info for .js Files (Pre-Compilation)

I would think that the experience that I described earlier for .ts files would be the same for .js files with JSDocs, but they aren't. Let's rebuild the scenario.

/**
 * You can count on me
 * @overload
 * @param {number} a NUMBER
 * @param {boolean} b BOOLEAN
 * @returns {void}
 */
/**
 * Does some string stuff
 * @overload
 * @param {string} a STRING
 * @param {object} b OBJECT
 * @returns {void}
 */
/**
 * @param {string | number} a
 * @param {boolean | object} b
 * @returns {void}
 */
function overloaded(a, b) {
  //
}

When I start typing out overloaded in VS Code, I don't see any JSDoc information for the overloads. This means I see neither the comments for the function nor the comments for the parameters. As I start providing parameters, the parameter documentation for the current parameter appears, but the documentation for the function itself is still absent. As with before, docs for parameters that I'm not currently supplying are absent because they are irrelevant.

If I type overloaded() and starting pressing ArrowDown/ArrowUp, I can toggle between the different overloads. However, the documentation for the function never appears. (The docs for the first parameter still appears as expected.)

If I hover overloaded (after providing proper arguments), then I get the no JSDoc information at all. No information about the function or the parameters is presented. I just see the types (parameter types and return type).

IDE (VS Code) Info for .js Files (Post-Compilation)

Oddly enough the experience that I described for the .js files changes after compilation. There's no need to rewrite the code, but I'll go through each scenario one-by-one again.

When I start typing out overloaded in VS Code, I see some of the JSDoc information. Specifically, I see the comment for the function in general. If I add a @template tag, then I also see that. However, I don't see any documentation for the parameters. This is the same experience that I get as I start providing parameters to the function. Documentation for the parameters never appears, although the parameters are still properly typed. The only thing that I see the entire time is the @overload tag, the function body comment, and @template (if it was present).

The above experience still occurs if I type overloaded() and start pressing ArrowDown/ArrowUp.
The above experience still occurs if I hover overloaded (after providing the proper arguments).

Conclusion

The .ts files provide the best and most consistent DX in terms of documentation. When using @overload in .js files, however, documentation information (not type information) is lost in one way pre-compilation and in another way post-compilation. I would like to have an experience in my .js files that's consistent with how the .ts files behave. (Again, not sure if this is a TS issue or a VS Code issue. If TS compiled @overload to look just like regular TS in .d.ts files, I'm assuming this issue wouldn't occur.)

Does that help?

[RyanCavanaugh]

OK, TL;DR

When the @overload tag exists, we shouldn't drop the description from the signature help

/**
 * neat
 * @overload
 * @param {string | number} a
 * @returns {void}
 */
function doSomething(a) { }
doSomething(/*signature help here*/1);