TypeScript: JSDoc tooltips are shared between types and values, but not functions

[schuelermine]

TS Template added by @mjbvz

TypeScript Version: 4.2.4

Search Terms

• quickinfo
• jsdoc

---

Issue Type: Bug

Steps to reproduce

• Create a TypeScript file.
• Create a type alias with some name, and write a JSDoc comment for it.
• For types and functions:
  • Create a function with the same name, write a different JSDoc comment.
  • Hover over the type name. You will see the function’s comment, followed by the type’s comment.
  • Hover over the function. You will only see the function’s comment.
• For types and values:
  • Create a value identifier with the same name, write a different JSDoc comment.
  • Hover over the type name. You will see the type’s comment, followed by the value’s comment.
  • Hover over the value identifier. You will see the type’s comment, followed by the value’s comment.

Reference file

/** A */
type X = null
/** B */
let X = null
/** C */
type Y = null
/** D */
function Y() {}

Screenshots

System and version info

VS Code version: Code - Insiders 1.56.0-insider (0123d26aaa393bccf99f31f1eac07df6c9e218ce, 2021-04-29T05:12:38.091Z)
OS version: Linux x64 5.11.0-7614-generic

System Info

Item	Value
CPUs	Intel(R) Core(TM) i5-8300H CPU @ 2.30GHz (8 x 2300)
GPU Status	2d_canvas: enabled gpu_compositing: enabled multiple_raster_threads: enabled_on oop_rasterization: disabled_off opengl: enabled_on rasterization: disabled_software skia_renderer: enabled_on video_decode: disabled_software vulkan: disabled_off webgl: enabled webgl2: enabled
Load (avg)	2, 2, 2
Memory (System)	7.64GB (0.18GB free)
Process Argv	--no-sandbox --unity-launch --crash-reporter-id dbbd25fe-3f4e-426a-9c89-45e060834124
Screen Reader	no
VM	0%
DESKTOP_SESSION	pop
XDG_CURRENT_DESKTOP	Unity
XDG_SESSION_DESKTOP	pop
XDG_SESSION_TYPE	x11

Extensions: none

[mjbvz]

Please share example code (as text) that demonstrates the issue

[schuelermine]

@mjbvz I have!

[RyanCavanaugh]

This is a story, not a bug report. What is the defect?

[schuelermine]

It should only display the JSDoc comment for the thing being hovered over, no?

[schuelermine]

Also, why is this an issue in TypeScript now? I’m confused.

[RyanCavanaugh]

TypeScript provides intellisense data to VS Code

There are a decent number of things where there's a value and a type with the same name but there's only documentation on one or the other, but users expect to see documentation regardless of which kind of identifier they're hovering on, so we show both. I'm not sure why that doesn't happen in the function case but for a declaration site, the behavior either way is immaterial IMO.

[schuelermine]

Well, I believe the correct behavior should be one of the following:

• When both are documented, show both, in a consistent order (either by declaration or fixed order), and with a separator (like a newline, a slash, or a pipe, or
• When only one is documented, show that on both, but, if both are documented, show the one that matches what’s being hovered over

[schuelermine]

I believe the different behavior with functions might be because TS hoists the function first, which moves it to the front of the tooltip.

[schuelermine]

In my opinion, the fact that the function tooltip only shows the function’s doc comment demonstrates that it’s possible to isolate the comments based on token type, and I believe that the second behavior I listed is unequivocally the better one.

[schuelermine]

This is a story, not a bug report. What is the defect?

I thought this was unintended behavior. Maybe it’s better to mark this as a feature request? I still believe the current implementation is unintuitive.