Repository navigation
Report XML doc parameter names as related symbol uses - #20637
xperiandri wants to merge 11 commits into
Conversation
✅ Release notes checked
|
|
Covered cases (
Scanner ( Reverting the emission in |
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
XML scanning and parameter collection miss valid cases and can produce incorrect references.
Review effort: Lite
Findings: 2
Open (2)
What changed in this PR
Adds opt-in XML documentation parameter references to compiler symbol-use data for future rename support.
Changes:
- Tracks XML documentation ranges and attribute references.
- Reports matching parameter and type-parameter references.
- Updates filtering, tests, API baseline, and release notes.
| File | Description |
|---|---|
tests/FSharp.Compiler.Service.Tests/XmlDocTests.fs |
XML reference scanning tests |
tests/FSharp.Compiler.Service.Tests/FSharp.Compiler.Service.SurfaceArea.netstandard20.bsl |
API baseline update |
tests/FSharp.Compiler.ComponentTests/FSharpChecker/SemanticClassificationRegressions.fs |
Classification regression tests |
tests/FSharp.Compiler.ComponentTests/FSharpChecker/FindReferences.fs |
Related-use tests |
src/Compiler/SyntaxTree/XmlDoc.fsi |
XML documentation reference API |
src/Compiler/SyntaxTree/XmlDoc.fs |
XML documentation scanning and ranges |
src/Compiler/Service/TransparentCompiler.fs |
Filters documentation uses |
src/Compiler/Service/SemanticClassification.fs |
Excludes documentation classification |
src/Compiler/Service/IncrementalBuild.fs |
Filters documentation uses |
src/Compiler/Checking/RelatedSymbolUse.fs |
Adds XML documentation use kind |
src/Compiler/Checking/NameResolution.fsi |
Reporting API declaration |
src/Compiler/Checking/NameResolution.fs |
Reports matching documentation references |
src/Compiler/Checking/Expressions/CheckExpressions.fs |
Reports function and member parameter references |
src/Compiler/Checking/CheckIncrementalClasses.fs |
Reports constructor references |
src/Compiler/Checking/CheckDeclarations.fs |
Reports type and union-case references |
docs/release-notes/.FSharp.Compiler.Service/11.0.200.md |
Release note |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
🔍 Tooling Safety Check — Affects-Agent-Config, Affects-Design-Time
|
2d83431 to
b8c43df
Compare
b8c43df to
42be88c
Compare
T-Gro
left a comment
There was a problem hiding this comment.
The diff is still way too big - apply the NoBloat instructions and CodeCompaction skill.
Especially the massive code comments would benefit not just with drastic reduction, but ideally with well named functions/arguments/bindings/types making the intention clear.
If a well named piece of code just tells what the comment says - delete the comment.
- Excluding public API documentation and comments inside test source strings, this diff still adds 60 new code comment lines and 5423 new code comment chars.
- Comments bypass the type system and become stale maintenance state. Keep only unusually durable Symbols API contracts; express implementation and test intent through names, functions, active patterns, discriminated unions, and types.
T-Gro
left a comment
There was a problem hiding this comment.
🤖🕵️ AI review — verify independently.
|
Compacted as requested in 97c3e2c, on top of current main (
The diff is +681/-38 (it was +866/-37). |
The compacted notes of dotnet#20598, dotnet#20599 and dotnet#20637 replace the lines they rewrote; the union merge had kept both. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
97c3e2c to
ba04f9f
Compare
Rename asks the checker for AllInCodeAndDocs, so the names dotnet#20637 reports inside the declaration's `///` comment are rewritten with the parameter, and a name on a `///` line gets the bare text. Document highlights include the tag name. Find All References and the refactorings ask for AllInCode and keep the doc names out. A union case field's tag is found through the check results of the file that declares it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Rename asks the checker for AllInCodeAndDocs, so the names dotnet#20637 reports inside the declaration's `///` comment are rewritten with the parameter, and a name on a `///` line gets the bare text. Document highlights include the tag name. Find All References and the refactorings ask for AllInCode and keep the doc names out. A union case field's tag is found through the check results of the file that declares it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Isn't it possible to mark [<Struct>] here too?
There was a problem hiding this comment.
It is possible, but it breaks an API that has already shipped, so I left it as is. GetUsesOfSymbolInFile has been public since 10.0.300 (PR #19361) with ?relatedSymbolKinds as an option: the surface area baseline lists FSharpOption<RelatedSymbolUseKind> in every tag from v15.2.300 to v15.2.403.
With [<Struct>] the parameter becomes FSharpValueOption<RelatedSymbolUseKind>. A caller compiled against the released package then fails with MissingMethodException, and a source caller that passes an option (?relatedSymbolKinds = Some kinds) stops compiling. TcSymbolUses.GetUsesOfSymbol is internal, which is why it could take [<Struct>] in 6871004; this member converts once, at the call.
If you want the break anyway, it touches the signature in the .fs and the .fsi, the surface area baseline and every caller that passes an option, and I will make it.
There was a problem hiding this comment.
Can we add an overload and deprecate the other?
There was a problem hiding this comment.
Done in b24fe43: GetUsesOfSymbolInFile now has an overload with [<Struct>] ?relatedSymbolKinds, and the option one is [<Obsolete>] and forwards to it.
Two overloads with optional parameters of the same shape make a bare GetUsesOfSymbolInFile(symbol) ambiguous (FS0041; F# does not prefer the non-obsolete one). So the obsolete overload now takes relatedSymbolKinds: RelatedSymbolUseKind option as a required parameter. Its IL signature is unchanged (the surface-area baseline keeps its line and gains one for the new overload), so binary callers keep working.
At the source level, calls with no kinds, cancellationToken = ..., relatedSymbolKinds = kinds and positional arguments bind to the new overload (checked with the F# 10.0.402 and the 11 compilers). Only ?relatedSymbolKinds = someOption has to pass a voption now; it fails with FS0044 + FS0818 otherwise. I updated the two tests that used it.
GetSemanticClassification(range option, ?relatedSymbolKinds) has the same shape; I left it alone. Say if you want it done the same way.
There was a problem hiding this comment.
GetSemanticClassification(range option, ?relatedSymbolKinds) is done the same way in e8223ff: a new overload with [<Struct>] ?relatedSymbolKinds, and the option one is [<Obsolete>], keeps its IL signature and forwards to it. TcResolutions.GetSemanticClassification and TypeCheckInfo.GetSemanticClassification take the struct option as well, so the new overload hands the value down without converting it.
The obsolete overload's relatedSymbolKinds is required for the same reason as above: GetSemanticClassification(range) stays unambiguous. GetSemanticClassification(range, kinds) and GetSemanticClassification(range, ?relatedSymbolKinds = voption) bind to the new overload, GetSemanticClassification(range, Some kinds) to the obsolete one (FS0044), and ?relatedSymbolKinds = someOption fails (FS0044 + FS0818).
Rename asks the checker for AllInCodeAndDocs, so the names dotnet#20637 reports inside the declaration's `///` comment are rewritten with the parameter, and a name on a `///` line gets the bare text. Document highlights include the tag name. Find All References and the refactorings ask for AllInCode and keep the doc names out. A union case field's tag is found through the check results of the file that declares it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Rename asks the checker for AllInCodeAndDocs, so the names dotnet#20637 reports inside the declaration's `///` comment are rewritten with the parameter, and a name on a `///` line gets the bare text. Document highlights include the tag name. Find All References and the refactorings ask for AllInCode and keep the doc names out. A union case field's tag is found through the check results of the file that declares it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
T-Gro
left a comment
There was a problem hiding this comment.
🤖🕵️ AI review — verify independently.
| /// <summary>Get any extra colorization info that is available after the typecheck</summary> | ||
| [<Obsolete("This overload is kept for binary compatibility. Use the overload that takes relatedSymbolKinds as a struct option: relatedSymbolKinds = kinds, or ?relatedSymbolKinds = a voption.")>] | ||
| member GetSemanticClassification: | ||
| range option * relatedSymbolKinds: RelatedSymbolUseKind option -> SemanticClassificationItem[] |
There was a problem hiding this comment.
🤖🕵️ FS0041 for previously valid inferred named arguments
module Call
open System.Threading
open FSharp.Compiler.CodeAnalysis
open FSharp.Compiler.Symbols
let call (r:FSharpCheckFileResults) (s:FSharpSymbol) k (kinds:RelatedSymbolUseKind option) (ct:CancellationToken) =
r.GetSemanticClassification(None, relatedSymbolKinds = k)`XmlDoc` keeps the range of every `///` line and lists the `name` and `cref` attribute values it contains with their source ranges. The checker reports each `<param>`, `<paramref>`, `<typeparam>` and `<typeparamref>` name that matches a parameter or type parameter of the documented declaration as a `RelatedSymbolUseKind.XmlDocParameter` use, for let-bound functions, members, primary constructors, union case fields and signature-file vals. The kind is opt-in: `GetUsesOfSymbolInFile` returns it only when asked for, the `ItemKeyStore` behind Find All References never receives it, and semantic classification ignores it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The scanner looked for the attribute name as a substring of each line, so `<param notname="wrong" name="x">` reported `wrong`, and a tag whose `name` sat on the next `///` line reported nothing. It now walks the attributes of each tag one at a time over the whole comment, keeps a `>` inside a quoted value from ending the tag, maps each value back to its line, and skips a value that runs over a line break. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review feedback. `GetRefs` parses the comment's own lines with
`XDocument` and line info instead of scanning the text, so a doc that
starts with plain text (an escaped summary), a badly formed doc and a
tag inside an XML comment name nothing, exactly as the compiler reads
them. `<include>` stays unexpanded: its content lives in another file.
`RelatedSymbolUseKind.AllInCode` asks for every related use except the
names inside comments and `AllInCodeAndDocs` for those too; `All` now
means `AllInCode`. `TcResolutions.CapturedRelatedSymbolUses` hands out
the uses in code only, so the symbol index and semantic classification
need no check of their own.
The tests mark the expected uses with `{ref}…{/ref}` instead of
spelling out coordinates.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review feedback. A caller compiled when `RelatedSymbolUseKind.All` was every bit still passes that mask, which admitted the names inside XML doc comments. `GetUsesOfSymbol` reads it as `AllInCode`, and `All` is obsolete in favour of the two names that say what they include; the callers in the repository move to `AllInCode`. `GetRefs` lost a value written on a later line than its attribute name, as in `<param name=` followed by `"x"/>`. It now follows the `=` and the opening quote across lines and maps the value to its own line. `XmlDoc` takes and returns `ImmutableArray` for the line ranges and the refs, the candidates for a doc name are `ImmutableArray`s of struct tuples built only when a sink is there to take them, and a related use is stored as a struct tuple. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`RelatedSymbolUseKind.All` is obsolete, and an obsolete case is an error in these projects. The record spread tests and the record type rename tests asked for `All`; they mean the related uses in code. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
`let id (x: 'T) = x` is generic through its annotation, not through a declaration, so `<typeparam name="T">` found nothing. An implementation now names the type variables its checking added to the unscoped environment next to the declared ones, and a signature val names the type parameters it generalizes. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The `cref` kind and the `see`, `seealso`, `exception` and `permission` scan had no consumer and are gone, with their tests and baseline lines.
Names replace the comments: `linesBeforeText`, `tripleSlashLength`, `allAsCompiledIntoOlderCallers`, `CapturedRelatedSymbolUsesInCode`.
The fact tests are labelled theory rows, and one `extractRefs` in FSharp.Test.Utilities replaces the two `{ref}` scanners.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…doc work - XmlDocTyparCandidates takes any sequence of type parameters, so the caller no longer builds a list for it. - TcSymbolUses.GetUsesOfSymbol takes its kinds as a struct optional argument; the public GetUsesOfSymbolInFile keeps its option. - tryFindFirstXmlLine finds the line with the new Array.tryFindIndexV, and the implicit summary lines trim and test a span instead of a string. - The XML text is built with an interpolated string, without the line break before the closing tag, which nothing reads. - extractRefs returns a struct tuple and loops by index. - The classification regression asserts on the collection itself. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e option one The new overload takes relatedSymbolKinds as a [<Struct>] optional parameter, so a call no longer allocates an option. The overload that takes a RelatedSymbolUseKind option stays for binary compatibility, is obsolete and forwards to the new one. Two overloads with optional parameters of the same shape make a bare GetUsesOfSymbolInFile(symbol) ambiguous (FS0041); F# does not prefer the non-obsolete one. The obsolete overload therefore takes relatedSymbolKinds as a required parameter, which leaves its IL signature unchanged. A call with no kinds, with cancellationToken = ... or with relatedSymbolKinds = kinds binds to the new overload on F# 10 and 11. A call that passes ?relatedSymbolKinds an option has to pass a voption instead. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…e the option one The same change as for GetUsesOfSymbolInFile in the previous commit. The new overload takes relatedSymbolKinds as a [<Struct>] optional parameter and hands it down without converting it: TcResolutions.GetSemanticClassification and TypeCheckInfo.GetSemanticClassification take the struct option too. The overload that takes a RelatedSymbolUseKind option stays for binary compatibility, is obsolete and forwards to the new one; its relatedSymbolKinds parameter is required so that GetSemanticClassification(range) is not ambiguous. Its IL signature is unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
e8223ff to
210f47d
Compare

Fixes #15134
Renaming a parameter in Visual Studio leaves
<param name="x">,<paramref>,<typeparam>and<typeparamref>in the declaration's///comment untouched (#20630), because the compiler kept a single range for the whole comment and reported nothing inside it.XmlDocnow keeps the range of every///line and lists thenamevalues of itsparam,paramref,typeparamandtypeparamrefelements with their source ranges, and the checker reports eachnamethat matches a parameter or type parameter of the declaration as aRelatedSymbolUseKind.XmlDocParameteruse — for let-bound functions, members, primary constructors, union case fields and signature-file vals.The new kind is opt-in:
GetUsesOfSymbolInFilereturns it only when asked for, and Find All References and semantic classification never see it, so symbol search stays free of documentation hits. The editor change that turns it into a rename of the tags follows in a separate PR.🤖 Generated with Claude Code