Include documentation from a variable's type when you hover the variable

[OmgImAlexis]

Issue Type: Feature request

I had hoped to see the description for the type when hovering over the value via intellisense, etc.

When I hover over context.slot I can see "The slot the disk is in." yet when I try hovering over const slot I see just the type. Is there anything to enable this? Even setting slot to Slot manually it still only shows the type.

 /** The slot the disk is in. */
type Slot = string;

interface Context {
    /** The slot the disk is in. */
    slot?: Slot
}

const func = (context: Context): Context => {
    const x = context.slot;
    const slot: Slot = context.slot;

    return {
        slot: x || slot
    };
};

func({
    slot: '1'
}).slot;

VS Code version: Code 1.43.2 (0ba0ca52957102ca3527cf479571617f0de6ed50, 2020-03-24T07:34:57.037Z) OS version: Darwin x64 19.2.0

System Info

|Item|Value| |---|---| |CPUs|Intel(R) Core(TM) i5 CPU M 520 @ 2.40GHz (4 x 2400)| |GPU Status|2d_canvas: unavailable_software
flash_3d: disabled_software
flash_stage3d: disabled_software
flash_stage3d_baseline: disabled_software
gpu_compositing: disabled_software
metal: disabled_off
multiple_raster_threads: enabled_on
oop_rasterization: disabled_off
protected_video_decode: disabled_off
rasterization: disabled_software
skia_renderer: disabled_off_ok
video_decode: disabled_software
viz_display_compositor: enabled_on
viz_hit_test_surface_layer: disabled_off_ok
webgl: unavailable_software
webgl2: unavailable_software| |Load (avg)|1, 1, 2| |Memory (System)|8.00GB (0.79GB free)| |Process Argv|.| |Screen Reader|no| |VM|0%|

Extensions (27)

Extension|Author (truncated)|Version ---|---|--- go-outliner|766|0.1.20 npm-intellisense|chr|1.3.0 path-intellisense|chr|1.4.2 jsrefactor|cms|2.20.5 vue-peek|dar|1.0.2 vscode-eslint|dba|2.1.2 EditorConfig|Edi|0.14.5 vscode-npm-script|eg2|0.3.11 flow-for-vscode|flo|1.5.0 todo-tree|Gru|0.0.171 docthis|joe|0.7.1 vscode-home-assistant|kee|1.6.1 dotenv|mik|1.0.1 vscode-docker|ms-|1.0.0 csharp|ms-|1.21.16 atom-keybindings|ms-|3.0.6 cpptools|ms-|0.27.0 Go|ms-|0.13.1 vscode-typescript-next|ms-|3.9.20200408 go-doc|msy|0.1.1 hide-gitignored|npx|1.1.0 vetur|oct|0.24.0 vscode-graphql|Pri|0.2.14 json-template|sto|0.3.1 vscode-icons|vsc|10.0.0 vscode-wakatime|Wak|4.0.0 vscode-go-autotest|win|1.6.0 (2 theme extensions excluded)

[mjbvz]

This is the expected behavior currently.

For the code:

 /** The slot the disk is in. */
type Slot = string;

You have documented the type Slot. This documentation will only show up when you hover over the type Slot in the file, and not when you hover over variables that are of the type Slot (as these variables can have their own documentation)

Having said that, it is a feature request to show the type documentation when you hover over a variable. Moving the issue upstream for more feedback

[mesqueeb]

I just want to add +1 to this being a feature request.

IF the variable or prop of an interface is a certain type, but doesn’t have it’s own documentation block, I strongly believe it should show the documentation of the underlying type.

[OmgImAlexis]

@mesqueeb that’s exactly what I was expecting.

[mohsen1]

How this could work for "mixed types"?

/** A */
type A = { foo: string; }
/** B */
type B = { bar: number; }

interface I {
  // what hover should show here?
  ab: A & B;

  // what hover should show here?
  ba: B & A;

  // what hover should show here?
  bOrA: B | A;
}

[OmgImAlexis]

@mohsen1 the intellisense for those already exists. We just want it also shown on the field it’s set to.

To see what they’d be just create a new type called C and set it to A & B and hover over.

[RyanCavanaugh]

Reference example

    /** Description */
    const slot: Slot = context.slot;

When you hover over slot, we show the description for the variable itself (in this case, "Description"). When you hover over Slot, we show the description for the type.

I think it's potentially very confusing to mix up these concepts and make it look like you're seeing documentation for one thing when it's actually documentation for the other thing. The type documentation is available a few pixels to the right, so it seems reasonable to have you hover there if that's the thing you're interested in.

[mesqueeb]

@RyanCavanaugh it's not about mixing. it's about having the type documentation as fallback for when there's no documentation provided for the variable.

And I'm talking about cases where the dev won't repeat the type after the variable, because it's already inferred from how the variable is created. In this case there's nothing "a little to the right" we can hover over...

[OmgImAlexis]

@RyanCavanaugh can you please remove the label as I've updated to show this as a feature request since you don't see this as a bug.

[mesqueeb]

@RyanCavanaugh @mjbvz

Here is a real use case of mine. I have a library that uses certain types through the entire library. Sometimes as function param types, sometimes as return types, etc...

The library then exposes a set of functions the dev that uses my library must implement.

In all cases below, IF there is no extra documentation provided for wherever MyProp is used, I would like it to fall back to the documentation of MyProp:

/**
 * Documentation on MyProp I want everything below to fall back to
 */
type MyProp = string

type SomeType = {
  n: number
  myProp: MyProp
}

type AnotherType = {
  x: string
  myProp: MyProp
}

type MyTuple = [MyProp, boolean]

export type ActionDevNeedsToImplement1 = (myProp: MyProp, n: number, x: string) => void
export type ActionDevNeedsToImplement2 = (someType: SomeType) => void
export type ActionDevNeedsToImplement3 = (anotherType: AnotherType) => void
export type ActionDevNeedsToImplement4 = (myTuple: MyTuple) => void

const action1: ActionDevNeedsToImplement1 = (myProp, n, x) => {
  // ❌ no documentation when hovering over `myProp`
  // ✅ documentation when the dev writes `myProp: MyProp` in the params and hovers over MyProp instead

  // requirements:
  // the library creator needs to export `MyProp`
}
const action2: ActionDevNeedsToImplement2 = (someType: SomeType) => {
  // ❌ no documentation on `MyProp` when hovering over `SomeType`
  // ❌ impossible to retrieve the documentation, because:
  //    the dev only sees this when hovering over SomeType
  //    { n: number, myProp: string }
}
const action3: ActionDevNeedsToImplement3 = (anotherType: AnotherType) => {
  // same as above
}
const action4: ActionDevNeedsToImplement4 = (myTuple: MyTuple) => {
  // same as above
}

My developers are having a hard time in all the cases above to know exactly what MyProp has to represent, unless I duplicate the documentation through all types underneath MyProp.

I want to avoid this duplication of documentation issue.

This is the reason this is an important feature request by @OmgImAlexis and myself.

If there are better ways to solve my issues without adding this feature and without duplication of documentation, please advise.

[mesqueeb]

@RyanCavanaugh will this suffice for your "Awaiting More Feedback" label?

[mjbvz]

Awaiting More Feedback means that we'd like feedback from more members of the community on whether this features would be useful

[zabaat]

This would be such a great feature for me! +1

[runspired]

I am actually astounded this is waiting for feedback and would happily add my plus one here.

I'll also propose a variant: show the type docs when hovering the type.

/** MyType description **/
interface MyType {}

/** myVar description **/
const myVar: MyType = {};

hover MyType should show MyType description, hover myVar should show myVar description.

Optionally, a toggle: show both var and type descriptions when hovering myVar, var description more prominent, type description either below or in a second panel that can be selected.

[trentcowden]

This would be super helpful for my projects!

[llllvvuu]

const action1: ActionDevNeedsToImplement1 = (myProp, n, x) => {
  // ❌ no documentation when hovering over `myProp`
  // ✅ documentation when the dev writes `myProp: MyProp` in the params and hovers over MyProp instead

  // requirements:
  // the library creator needs to export `MyProp`
}

This is a major use-case for me, rather than having to hit go-to-definition, potentially multiple times. Even if the type annotation is there, scrolling up/jumping up is a bit of friction.

FWIW there is Go To Type Definition and I have my Neovim configured to pop it up as a preview rather than immediately jump to the file (though for some reason this feature often returns no results although that might be an issue with my config)

[thelegendtubaguy]

Very surprised to see that this isn't a thing already!

[adamscybot]

Isn't TSDoc / JSDoc @inheritDoc the answer to this? Alas, it doesn't work in vscode with latest typescript (or ever as far as I know).

TSDoc support in general across TS itself/vscode (I know its sort of both, but I don't know the details of how it works) is extremely patchy and one of the most neglected areas of TS imo.