Reading unfamiliar code, I can't see what a name is without jumping away to its definition #574

Opportunity

Reading a PR or code I don't know yet, I keep meeting names I can't place: in var plan = Resolve(request, options); I want to know what plan is, what Resolve takes and what its doc comment says. Today the only way to find out is Go to definition (Ctrl+G D, gd): it opens another file, loses my place, makes me read a whole declaration for one line, then I press Back. Over a few dozen names in a review, that's most of the reading.

The vision's user "spend[s] most of their time navigating code bases, reviewing PRs and trying to understand existing/new code" (docs/vision.md), and VS Code (Show or Focus Hover, Ctrl+K Ctrl+I) and JetBrains (Quick Documentation, Ctrl+Q) both answer this in place. So does Helix in the terminal (Space k, LSP docs). TuiCode already runs a language server per language (#454, #456) and asks it for definitions and usages, but never for what's under the cursor: Languages/LanguageServer.cs doesn't ask for hover, and nothing in origin/main (96cd453) shows it.

Options considered

1. Do nothing; keep using Go to definition and Back. Costs nothing, and it works where the server is slow or missing. But it's the pain above: a file switch per name, and the doc comment is buried in the declaration.
2. Show it on the status bar. The type or signature of the name under the cursor on one row, refreshed as the cursor moves (like Vim's echodoc). It never gets in the way, but one row truncates any real signature, drops the doc comment altogether, and asking the server on every cursor move is wasted work over SSH.
3. A Quick info box at the cursor, on a key. One command asks the server for hover at the caret and shows its answer (signature, then doc comment) in a small bordered box just under the line, or above it if there's no room. It's what VS Code and JetBrains do from the keyboard, and it reuses Go to definition's plumbing and rules.
4. A peek of the definition inline (VS Code's Peek Definition): the declaration's source in an embedded editor under the line. It shows more, but it's a second editor inside the first, far more to build, and it's still the declaration rather than the short answer. Worth revisiting once Quick info exists.

Choosing 3: it's the smallest thing that answers "what is this?" without leaving the line, and it's what the users we learn from reach for. Option 2's one row can't hold a doc comment, and option 4 is a much bigger build for a different question.

Proposal

A new command, Quick info (Ctrl+G I, gi, Editor scope), in the palette and the Go menu next to Go to definition (menu letter i).

• It asks the file's language server what's under the caret and shows the answer in a box anchored to the caret's line: below it, or above it when there's more room there. The box is as wide as the answer needs, up to the editor's width, and up to 12 rows tall.
• The answer's code (the signature) is highlighted with the file's own grammar; the doc comment is wrapped prose under it. If it's longer than the box, ↑/↓/PgUp/PgDn scroll it.
• Esc closes it and leaves the cursor where it was. Enter closes it and goes to the definition, as gd would. Any other key closes it and acts in the editor as usual, so reading on is one keypress.
• Its keys are shown as buttons along its bottom border (Esc Close, Enter Go to definition), per the style guide's one-affordance rule, and F1 lists them.
• When there's no answer, it says so on the status bar the way gd does: Nothing to show here, the server still loading, or no server for this language (with the install hint gd already gives). Only the latest request shows, so a slow answer to an earlier press is dropped.

Mockup

  12 │    public async Task<Plan> RunAsync(Request request)
  13 │    {
  14 │        var plan = Resolve(request, options);
     │                   ┌ Quick info ─────────────────────────────────┐
  15 │        if (plan.│ Plan Planner.Resolve(Request request,         │
  16 │            retur│                      PlanOptions options)     │
  17 │                 │                                                │
  18 │        await _st│ Works out which steps a request needs, in the │
  19 │    }            │ order they must run. Returns an empty plan    │
  20 │                 │ when the request is already satisfied.        │
     │                 └─[ Esc Close ]──[ Enter Go to definition ]─────┘

Scope

In: the command, its key and mnemonic, the box, highlighting the signature, scrolling, the status-bar messages, and asking the server for hover (including saying so when initializing it). Any language with a server configured in Settings › Language Servers gets it, not just C#.

Out: showing it on mouse hover (a follow-up, if the terminals' mouse-move reporting makes it worth it); signature help while typing a call's arguments; showing several servers' answers; links inside the doc comment; a peek of the definition (option 4).

Delivery

One PR.

Decided

All of these were the Lead's, accepted when the stakeholder approved the pitch.

• Ctrl+G I / gi. Ctrl+G is already the family for "about the code under the cursor" (definition, usages, blame), I (info) is free there, and gi is no other mnemonic's prefix. VS Code's Ctrl+K Ctrl+I would clash with Ctrl+K (cut to end of line), and JetBrains' Ctrl+Q is Quit.
• On a key, not on every cursor move. Keyboard-first, and it doesn't send the server a request for each step of the cursor over a slow link.
• Named "Quick info". It's Visual Studio's and JetBrains' word for it; "hover" describes the mouse, which this doesn't use.
• Enter goes to the definition. It's the natural next step when the box isn't enough, and it saves a second chord.
• Any other key closes the box and still acts. Otherwise reading on costs Esc first every time.
• Up to 12 rows, then it scrolls. Enough for a signature and a short doc comment without hiding most of a laptop-sized editor.

Original idea

Reading unfamiliar code, I can't see what a name is (its type, its signature, its doc comment) without jumping away to where it's defined.

When I'm reading a PR or code I don't know yet and come to var plan = Resolve(request, options);, I want to know what plan is, what Resolve takes and what its doc comment says. Right now TuiCode's only way to find out is Go to definition (gd): it opens another file, leaves my place, and I read a whole declaration to get one line, then Back. Over a few dozen names in a review, that's most of the reading.

Evidence: TuiCode already runs a language server for C# and others (#454, #456) but never asks it for hover; VS Code (Show or Focus Hover), JetBrains (Quick Documentation) and Helix (Hover documentation, Space k) all show it in place.