Doc comments across the bundled libraries already cross-reference declarations with [Symbol],
and none of it resolves. Current counts:
| source |
[Foo] |
[`Foo`] |
tolk-stdlib |
60 |
0 |
types |
64 |
0 |
emulation |
99 |
1 |
| our smart contract wallet |
14 |
488 |
From tolk-stdlib/common.tolk:
/// Addresses are comparable with `==` operator, they have methods like [address.getWorkchain].
/// Similar to [mulDivFloor], but rounds the result: round(x * y / z).
/// note: this option controls [T.fromCell] and [T.fromSlice], but is ignored by [slice.loadAny];
The line that gives it away is in emulation/config.tolk:
/// Configuration parameters are defined in the [`block.tlb`](https://github.com/ton-blockchain/...)
That one renders and navigates, since hover is already markdown. So rendering isn't the gap.
There's just no way to aim a link at a declaration, which leaves a hand-written external URL as
the only thing that works, and only for targets outside the codebase.
Proposal
Resolve the bracketed targets in an extracted doc comment against the index and rewrite the hits
as links, before the string reaches the hover response. extractCommentsDoc looks like the
natural seam, and the name-keyed lookup in AddImport.ts:70-75 (at 342d87c) already answers
the same question a doc link asks.
Two things worth pinning down first.
Both spellings
Our row inverts the libraries: 14 plain against 488 backticked. Same convention either way, just
spelled differently, and neither spelling is wrong. So the resolver wants to strip backticks and
treat the two as one form, otherwise it covers most of one codebase and almost none of the other.
Bare names
A qualified target has a declaration to point at. A bare one doesn't, and the libraries use both:
Those name parameters and struct fields. In rustdoc neither would resolve bare: a parameter isn't
a linkable item at all, and a field is one but has to be reached through a path naming its owner,
not picked up from the enclosing type. Anything left unresolved becomes a
broken_intra_doc_links warning. Tolk could copy that, or search the enclosing declaration's
params and fields and link inside the same hover. Either works. It only needs deciding because
it fixes what counts as unresolved.
The diagnostic
Which is the half I actually care about. Once targets resolve, a [Symbol] left stale by a
rename becomes detectable, and a doc comment stops quietly outliving the thing it names. Wants
its own flag, presumably, since bare names would light up the bundled libraries on day one.
Happy to send a PR for the resolver and the diagnostic once the bare-name question has an answer.
Doc comments across the bundled libraries already cross-reference declarations with
[Symbol],and none of it resolves. Current counts:
[Foo][`Foo`]tolk-stdlibtypesemulationFrom
tolk-stdlib/common.tolk:The line that gives it away is in
emulation/config.tolk:That one renders and navigates, since hover is already markdown. So rendering isn't the gap.
There's just no way to aim a link at a declaration, which leaves a hand-written external URL as
the only thing that works, and only for targets outside the codebase.
Proposal
Resolve the bracketed targets in an extracted doc comment against the index and rewrite the hits
as links, before the string reaches the hover response.
extractCommentsDoclooks like thenatural seam, and the name-keyed lookup in
AddImport.ts:70-75(at342d87c) already answersthe same question a doc link asks.
Two things worth pinning down first.
Both spellings
Our row inverts the libraries: 14 plain against 488 backticked. Same convention either way, just
spelled differently, and neither spelling is wrong. So the resolver wants to strip backticks and
treat the two as one form, otherwise it covers most of one codebase and almost none of the other.
Bare names
A qualified target has a declaration to point at. A bare one doesn't, and the libraries use both:
Those name parameters and struct fields. In rustdoc neither would resolve bare: a parameter isn't
a linkable item at all, and a field is one but has to be reached through a path naming its owner,
not picked up from the enclosing type. Anything left unresolved becomes a
broken_intra_doc_linkswarning. Tolk could copy that, or search the enclosing declaration'sparams and fields and link inside the same hover. Either works. It only needs deciding because
it fixes what counts as unresolved.
The diagnostic
Which is the half I actually care about. Once targets resolve, a
[Symbol]left stale by arename becomes detectable, and a doc comment stops quietly outliving the thing it names. Wants
its own flag, presumably, since bare names would light up the bundled libraries on day one.
Happy to send a PR for the resolver and the diagnostic once the bare-name question has an answer.