Skip to content

Commit e67f5b9

Browse files
committed
docs: the hover rendering contract, and the work still open
`docs/hover-render.md` states the rule the rendering now follows (every character from the model, the declaration's text as input at most), what is done, and the open list in the order the items block each other: `type_of` losing its shape match, the two readings, and the small gaps this pass measured (`std::less<>`, a template-id callee, the prose types, `the_type_the_macros_leave`, declarator `const`, operator hovers, constructor resolution, base access, function-pointer parameters, the lambda `value` miscolouring). `docs/buglist.md` #27 records the report, what replaced the slicing, and why the `shared_ptr` problem is #28's root cause rather than a rendering one.
1 parent 09939af commit e67f5b9

2 files changed

Lines changed: 116 additions & 0 deletions

File tree

‎docs/buglist.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -571,3 +571,24 @@ deduce `int` — so the `/p` fixtures' shared cache at `C:\p\.cppls` served the
571571
`type_a_return_states`, `type_a_return_states_with`, `type_with_the_auto_parameters`) and the declaration geometry that
572572
predates them (`function_suffix_in`, `is_marked_maybe_unused`, which scans backwards through the text for `[[maybe_unused]]`
573573
when the attribute is a node). Those are the next batch, then `scopes.rs`.
574+
575+
## 27. Hover is rendered, not quoted — and what that exposed
576+
577+
`docs/hover-render.md` now holds the contract and the open list; this entry records why it exists and what it found.
578+
579+
**The report**: "most hover results are a copy of the source range rather than a reconstruction — no copy-paste display;
580+
redo the rendering modelled on Rust, especially for generics." It was true: the card chose between the declaration's raw
581+
text (`declaration_text`), the fact's strings joined by `signature_line`, a `template <…>` cut out of the file
582+
(`the_template_head_before`), and a macro-ridden return type repaired by slicing the specifier sequence. The anonymous
583+
struct in `handshake.rs`'s instantiation test showed `unsigned char` only because the body was copied.
584+
585+
**What replaced it**: `cpp_code_analysis::sema::render` — types through `Type`'s writer, parameters parsed and rebuilt,
586+
template heads from the declaration's parameters, classes by their node's keyword, reflection annotations from the fact.
587+
The card, the overload list and the member list all print it; the eight text-slicing helpers are gone. A member of a
588+
known specialization renders instantiated, so `Box<int>::put` reads `const int& value`.
589+
590+
**The bug this exposed is #28's root cause, not a rendering bug**: `DeclFact::type_of` is recovered by a range lookup
591+
and can be `None` for a declaration whose *later* text changed — measured on `bits/shared_ptr.h`, on truncations of it,
592+
and on a fixture ending in an unterminated `/**`. That is why `shared_ptr` keeps coming back: `element_type` loses the
593+
field, the arrow falls back to the pointer's own members, and the popup looks plausible. The repair plan is in
594+
`docs/hover-render.md` §1, together with the two-readings question (§2) and the small gaps this pass found (§3).

‎docs/hover-render.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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

Comments
 (0)