|
| 1 | +# Hover rendering — the contract, and what is still open |
| 2 | + |
| 3 | +The hover card's code block is **generated**, never sliced out of the file. One module decides it, |
| 4 | +`cpp_code_analysis::sema::render`, and the card, the overload list and the member list all print from it: |
| 5 | + |
| 6 | +```text |
| 7 | +render::an_item(fact, syntax, value) -> Vec<String> the declaration, with its template head |
| 8 | +render::a_line(fact, syntax, value) -> String one line, for a list |
| 9 | +render::a_type(written) -> String a spelling through `Type`'s writer |
| 10 | +render::parameters(written) -> Vec<Parameter> the recorded list, parsed and rebuilt |
| 11 | +``` |
| 12 | + |
| 13 | +The rule for anything added here: **every character is a product of the model**. A type is a `Type` printed by its own |
| 14 | +writer; a parameter list is parsed; a template head is built from the declaration's parameters; an annotation is |
| 15 | +`ReflectionFact::said()`. The declaration's text is input at most (a spelling the fact recorded), never output. |
| 16 | + |
| 17 | +## Done |
| 18 | + |
| 19 | +* Functions and methods: modifiers (`static`, `inline`, `constexpr`, `virtual`, `explicit`), return type, name, |
| 20 | + parameters with types/names/defaults/packs, and the trailing clause (`const`, `&`, `&&`, `override`, `final`, |
| 21 | + `= delete`, `= default`, `requires`). |
| 22 | +* Classes: the keyword its node kind carries (`class`/`struct`/`union`), bases, `enum`/`enum class`, the reflection |
| 23 | + annotation above it. |
| 24 | +* Aliases (`using X = Y;`), variables (`static`/`constexpr`/`const`/`volatile`, a folded constant's value), enumerators |
| 25 | + (`Red = 1`), namespaces. |
| 26 | +* Generics: template heads with kinds, defaults and packs; **members of a known specialization render instantiated** |
| 27 | + (`Box<int>::put` shows `const int&`, not `const T&`); a class use shows its own spelling as |
| 28 | + `As written here: \`Box<int>\``. |
| 29 | +* The fact/parser repairs the rendering needed: `typename` stripped by the type reader; `members_of` retrying the |
| 30 | + qualified spelling; `qualified_from_the_index` taking the class declaration rather than a constructor; |
| 31 | + `finish_a_nested_name` following a head that is another class; an unresolved pointee refused instead of returned; |
| 32 | + `CppTemplateParam::{is_type_param,get_name}` searching the subtree. |
| 33 | + |
| 34 | +## Open — in the order they block each other |
| 35 | + |
| 36 | +### 1. `DeclFact::type_of` loses its shape match (the `shared_ptr` root cause) |
| 37 | + |
| 38 | +A fact's type is **recovered** by matching a binding to a syntax shape by range at summary-build time. When that match |
| 39 | +misses, the field becomes `None` silently. Measured with `inspect facts` on `bits/shared_ptr.h` and truncations of it: |
| 40 | + |
| 41 | +| input | `element_type`'s `type_of` | |
| 42 | +| --- | --- | |
| 43 | +| lines 1..191 (stops right after the declaration) | present | |
| 44 | +| lines 1..197 (the class's `#ifdef … #endif` block comes after it) | missing | |
| 45 | +| the whole file | missing | |
| 46 | +| lines 174..197 alone | present | |
| 47 | +| lines 1..55 + the class | missing | |
| 48 | +| lines 1..80 + the class | present | |
| 49 | +| a fixture whose **last** token is an unterminated `/**` | missing | |
| 50 | + |
| 51 | +So a field that belongs to a declaration is destroyed by text **after** it, which means it is not being read from the |
| 52 | +declaration. The plan: |
| 53 | + |
| 54 | +1. When the shape lookup misses, read the type from the binding's own `range` (it is the declaration's range) — a |
| 55 | + fallback in `declared_type_of_with` that cannot miss. |
| 56 | +2. Count the misses (`inspect stats`) so the bug is visible instead of silent. |
| 57 | +3. Then re-check `std::shared_ptr<Resource>::element_type` on `test_cpp`; the hand-written two-file fixture already |
| 58 | + passes (`the_class_after_the_operator("shared_ptr<Resource>") == Some("Resource")`). |
| 59 | + |
| 60 | +### 2. The two readings |
| 61 | + |
| 62 | +`FileIndexer::index` (the file's own text) and `index_rendering` (the cooked stream, ranges mapped back) both produce |
| 63 | +summaries, and the same class can be described differently by them: `inspect facts` reads the first, a hover may use the |
| 64 | +second. A fix verified in one can regress in the other — this is why `shared_ptr` has been "fixed" several times. The |
| 65 | +open question is the design: one summary per file with both answers for the fields that differ, or a rule that every |
| 66 | +query reads the reading that produced the fact it started from. |
| 67 | + |
| 68 | +### 3. Gaps this pass found, each small and self-contained |
| 69 | + |
| 70 | +* **`std::less<>` renders `std::less`.** `parse_type_spelling` drops an empty argument list, which changes what the name |
| 71 | + means. `Type::Named` needs to keep "had an empty list" (or the name keeps `<>`). |
| 72 | +* **A hover on a template-id callee answers nothing.** `std::make_shared<Resource>(2)` — the callee is a template-id, not |
| 73 | + a plain name, and the name lookup at that offset finds neither. (Measured on `test_cpp/src/smart_pointers.cpp:50`.) |
| 74 | +* **The prose around the card still prints raw fact strings** — ``returning `std::vector<std::string> &` `` in |
| 75 | + `kind_words`. Route those through `render::a_type` too. |
| 76 | +* **`the_type_the_macros_leave` is a fact-level repair still in hover.** It rebuilds a return type that a macro's name |
| 77 | + swallowed (`WINBASEAPI WINBOOL WINAPI SetConsoleOutputCP`). It should live where facts are built; hover should not |
| 78 | + own a text repair at all. |
| 79 | +* **`const`/`volatile` restored only from specifiers.** A `Foo* const p` writes its `const` in the declarator; the card |
| 80 | + says `Foo* p`. Reading the declarator's own qualifier is the missing half (the fact drops both). |
| 81 | +* **Operator hovers hit the keyword vocabulary popup.** On `operator bool`, the cursor is on `operator` and the |
| 82 | + keyword popup wins over the declaration. The card should be the declaration; the vocabulary is for a name that is |
| 83 | + not one. |
| 84 | +* **A constructor's name resolves to the type.** Hovering `Derived` in `Derived() = default;` shows `struct Derived` |
| 85 | + rather than the constructor, because the name is both. |
| 86 | +* **Bases are printed without their access** (`: Base`), which is right for a fact (it does not record the access) and |
| 87 | + wrong for a class whose base clause says `public`; the syntax has it. |
| 88 | +* **Function-pointer parameter types** print as the model's unparsed name; `int (*cb)(int)` deserves `Type::Function`. |
| 89 | +* **`value` in a lambda is coloured `method`** (`test_cpp/src/smart_pointers.cpp:64`). The use does not resolve to the |
| 90 | + lambda's parameter and falls through to the index, where a member function called `value` matches. Needs a |
| 91 | + reproducer in a fixture first. |
| 92 | +* **Doc comments** are still the file's text, deliberately: they *are* documentation, and `render_documentation` formats |
| 93 | + them as blocks. If that changes, it is a separate decision from the code block. |
| 94 | +* **`diagnostics_stable`'s `a_finding_does_not_vanish_between_first_and_second_pull`** times out on a warm cache |
| 95 | + (120 s) and passes on a cold one. Unrelated to hover; noted because it makes the full suite look red. |
0 commit comments