Skip to content

Resolve cref links in hover and documentation - #1527

Merged
TheAngryByrd merged 4 commits into
ionide:mainfrom
NatElkins:fix-cref-documentation-links
Aug 31, 2026
Merged

TheAngryByrd merged 4 commits into
ionide:mainfrom
NatElkins:fix-cref-documentation-links

Conversation

@NatElkins

@NatElkins NatElkins commented Apr 10, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • render resolved <see cref> and <seealso cref> targets with clean display text
  • include source file, line, and column in documentation command links returned from hover and documentation APIs
  • keep documentationSymbol resilient when matching symbols from metadata

Why

The original issue started in tooltip formatting, but there was a second problem in the click path. Hover links only carried the target symbol, so the VS Code side sometimes had to fall back to the current cursor position when resolving the clicked link. If the cursor had already moved, the Info Panel could open the wrong symbol or stay blank.

This change makes the link payload self-contained. The new source-context fields are optional, so existing callers still work.

Testing

  • dotnet fantomas --check build.fsx src
  • dotnet test test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj -f net8.0 --filter "cref link integration tests"
  • local VS Code repro through Ionide using the patched build, confirming hover x then click Async opens Async docs across fresh launches

Context

@baronfel

Copy link
Copy Markdown
Contributor

Ok this is sick as hell

@NatElkins

Copy link
Copy Markdown
Contributor Author

Pushed follow-up commit a0c3a8d with the Fantomas output for the three files the previous run flagged (TipFormatter.fs, TipFormatter.fsi, CommandResponse.fs).

Local verification on that commit:

  • dotnet fantomas --check build.fsx src
  • dotnet build test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj -f net8.0
  • dotnet run -f net8.0 --project test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj -- --sequenced --no-spinner --filter-test-list TipFormatter --summary
  • dotnet run -f net8.0 --project test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj -- --sequenced --no-spinner --filter-test-list "cref link integration tests" --summary

GitHub created a new workflow run for a0c3a8d, but it is currently action_required with no jobs (https://github.com/ionide/FsAutoComplete/actions/runs/24257221924). That appears to be the fork-run approval gate rather than a code/test failure.

@NatElkins

Copy link
Copy Markdown
Contributor Author

This still isn't quite ready actually, will drop a note when it's tested to my satisfaction.

@NatElkins

Copy link
Copy Markdown
Contributor Author

Okay I'm good with this now.

@github-actions

Copy link
Copy Markdown
Contributor

🤖 This is an automated response from Repo Assist.

Great contribution, @NatElkins! This PR addresses a long-standing quality gap in F# hover documentation. A few observations:

What this adds (nicely):

  1. <see cref="..."> resolution — XML doc links now become navigable references in hover tooltips. The approach of building a lookup dict from GetAllEntities and passing the resolver in is clean and avoids repeated enumeration per call.
  2. Source location context in documentationCommand links — including file/line/column makes jump-to-definition from hover links more reliable.
  3. More resilient TryGetFormattedDocumentationForSymbol — the added union case handling and the matchesSymbol/matchesAbbreviatedEntity helpers should fix silent failures for certain symbol types.

One thing worth confirming:

The createCrefResolver enumerates all entities across referenced assemblies via GetAllEntities false. If it is invoked per-hover or per-completion-resolve on a large project this could add latency. It is worth verifying the resolver is either cached per project-snapshot or that entity enumeration is already cheap by the time it is called here.

If this is already handled, feel free to disregard — just flagging it as a potential hot path concern.

Overall this is well-structured and fills a real usability gap. Nice work!

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@7ee2b60744abf71b985bead4599640f165edcd93

@NatElkins

Copy link
Copy Markdown
Contributor Author

Good call. It was being rebuilt in the hover and documentation paths for the same ParseAndCheckResults snapshot.

I pushed f0adfdec, which caches both GetAllEntities and the cref resolver per ParseAndCheckResults instance, then switches the hover / documentation call sites to reuse that cached resolver. That makes the resolver lifetime match the typecheck snapshot instead of rebuilding it per request.

Rechecked with:

  • dotnet fantomas --check build.fsx src
  • dotnet test test/FsAutoComplete.Tests.Lsp/FsAutoComplete.Tests.Lsp.fsproj -f net8.0 --filter "cref link integration tests"

@TheAngryByrd
TheAngryByrd force-pushed the fix-cref-documentation-links branch from f0adfde to 7f29134 Compare August 31, 2026 11:12
@TheAngryByrd
TheAngryByrd enabled auto-merge (squash) August 31, 2026 11:18
@TheAngryByrd
TheAngryByrd disabled auto-merge August 31, 2026 11:19
@TheAngryByrd
TheAngryByrd merged commit 2a5b152 into ionide:main Aug 31, 2026
19 checks passed
nojaf added a commit that referenced this pull request Oct 10, 2026
Three fixes that came out of measuring FSAC's memory on the Fantomas
solution with the transparent compiler. One commit each. `CHANGELOG.md`
gets a 0.85.1 section, so merging this publishes 0.85.1.

## Changes

- **Build the cref resolver only when a doc comment has a cref**
(`ParseAndCheckResults.fs`). Hover asked for the resolver on every
tooltip, and building it lists every entity of every referenced
assembly. Now it is built on the first cref it resolves. This came in
with #1527, so 0.85.0 has it.
- **Skip files without the symbol's name in Find References**
(`AdaptiveServerState.fs`, `String.containsIdentifier` in `Utils.fs`).
FCS 43.12 imports all references of a project before it parses a file of
it, also when the file then fails FCS's own identifier test. FSAC now
checks the text of the file for the name as a whole identifier first.
FCS takes its identifiers from the tokens of the file, so this skips no
file FCS would search. Transparent compiler only: the background
compiler path searches without an identifier test, so the filter could
change its results.
- **Make `DisableInMemoryProjectReferences` work again**
(`ProjectWorkspace.fs`, `AdaptiveServerState.fs`). It has done nothing
since #1174. With the setting on, a referenced F# project comes from its
output DLL, for both compilers, and Find References follows MSBuild's
project references to find dependent projects. The unused
`FSharpCompilerServiceChecker.DisableInMemoryProjectReferences` property
is removed. The setting stays off by default: a DLL does not show
changes made since the last build.

## Results

Fantomas solution, transparent compiler, replaying a reading session:
open `CodePrinter.fs`, hover, navigate, read `SyntaxOak.fs`, then Find
References on `SyntaxOak.Expr`.

| | Before | After |
|---|--:|--:|
| Memory at the end of the session | 1,170 MB | 770 MB |
| Memory added by the first hover | 65 MB | 1 MB |
| Memory added by Find References | 480 MB | 215 MB |
| First hover | 1.1 s | 50 ms |
| Find References | 3.0 s | 1.5 s |

Averages of four runs before and three after; runs differ by up to 40
MB. Find References returns the same 672 references in 9 files before
and after, and with `DisableInMemoryProjectReferences` on.

## Tests

- `CoreUtilsTests.fs`: `String.containsIdentifier` (whole identifiers,
`'a`, backticks, operators).
- `SnapshotTests.fs`: with the setting on, Console1 references
`Library1.dll` as a PE reference.
- Full suite, net10.0, both compilers: 5,863 passed, 0 failed.

## Related

- dotnet/fsharp#20704 parses a file without the bootstrap info. With it,
FCS would not import references for a file that fails the identifier
test, and the text filter here would only save the parse.
- dotnet/fsharp#20755: the transparent compiler keeps every file's name
resolution sink, whatever `keepAllBackgroundResolutions` and
`keepAllBackgroundSymbolUses` say.
- ionide/proj-info#248: MSBuild's in-process node keeps the evaluated
projects, about 45 MB here.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants