Skip to content

Report XML doc parameter names as related symbol uses - #20637

Open
xperiandri wants to merge 11 commits into
dotnet:mainfrom
xperiandri:fix/xmldoc-param-symbol-uses
Open

xperiandri wants to merge 11 commits into
dotnet:mainfrom
xperiandri:fix/xmldoc-param-symbol-uses

Conversation

@xperiandri

@xperiandri xperiandri commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

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. XmlDoc now keeps the range of every /// line and lists the name values of its param, paramref, typeparam and typeparamref elements with their source ranges, and the checker reports each name that matches a parameter or type parameter of the declaration as a RelatedSymbolUseKind.XmlDocParameter use — for let-bound functions, members, primary constructors, union case fields and signature-file vals.

The new kind is opt-in: GetUsesOfSymbolInFile returns 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

Copilot AI lite review requested due to automatic review settings September 26, 2026 01:38
@xperiandri
xperiandri requested a review from a team as a code owner September 26, 2026 01:38
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

✅ Release notes checked


✅ Found changes and release notes in following paths:

Change path Release notes path Description
`vsintegration/src` docs/release-notes/.VisualStudio/18.vNext.md

@xperiandri

Copy link
Copy Markdown
Contributor Author

Covered cases (FSharpChecker/FindReferences.fs, module XmlDocParameters; each asserts that the default GetUsesOfSymbolInFile excludes the doc ranges, that relatedSymbolKinds = XmlDocParameter includes them at the exact ranges, and that UnionCaseTester ||| CopyAndUpdateRecord still excludes them):

  • <param> and <paramref> of a let-bound function
  • <param> of a member, not confused with this
  • <param> of a primary constructor, documented on the type
  • <param> of a union case field
  • <param> of a signature-file val: the code use is found, the doc use stays out of the findAllReferences workflow (the ItemKeyStore path)
  • <typeparam> of a generic type; <typeparam> and <typeparamref> of an explicitly generic function ('T matches name="T")
  • a backticked parameter is matched by its bare name
  • a duplicated name reports every occurrence
  • an unknown name reports nothing and does not break the others
  • <inheritdoc> and <include> do not disturb the scan

Scanner (FSharp.Compiler.Service.Tests/XmlDocTests.fs, module XmlDocRefs): spaces around =, single-quoted values, attribute order, self-closing tags, a tag split across /// lines, malformed XML, and an XmlDoc without line ranges ([||]). SemanticClassificationRegressions: nothing inside the /// block is classified.

Reverting the emission in ReportXmlDocRefUses fails 10 of the 11 FindReferences tests; removing the ItemKeyStore filter fails the signature-file one.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

XML scanning and parameter collection miss valid cases and can produce incorrect references.

Review effort: Lite
Findings: 2 Medium severity

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

Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
@github-actions github-actions Bot added the ⚠️ Affects-Design-Time Tooling check: PR touches type providers or dependency manager label Sep 26, 2026
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions github-actions Bot added the ⚠️ Affects-Agent-Config Tooling check: PR modifies AI agent instructions or workflows label Sep 27, 2026
@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

This comment has been minimized.

@github-actions

Copy link
Copy Markdown
Contributor

🔍 Tooling Safety Check — Affects-Agent-Config, Affects-Design-Time
Affects-Agent-Config: Changes agent configuration files.
Affects-Design-Time: Changes language-server behavior.

Generated by PR Tooling Safety Check · gpt56 2.5M · ◷

@T-Gro T-Gro added the AI-reviewed PR reviewed by AI review council label Sep 29, 2026
@T-Gro
T-Gro self-requested a review September 29, 2026 09:26
@xperiandri
xperiandri force-pushed the fix/xmldoc-param-symbol-uses branch from 2d83431 to b8c43df Compare October 8, 2026 01:11

@T-Gro T-Gro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 🕵️ Re-reviewed all recent changes as of b8c43df; 1 finding

@xperiandri
xperiandri force-pushed the fix/xmldoc-param-symbol-uses branch from b8c43df to 42be88c Compare October 10, 2026 22:28

@T-Gro T-Gro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@github-project-automation github-project-automation Bot moved this from New to In Progress in F# Compiler and Tooling Oct 13, 2026

@T-Gro T-Gro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖🕵️ AI review — verify independently.

@xperiandri

Copy link
Copy Markdown
Contributor Author

Compacted as requested in 97c3e2c, on top of current main (fbc9be3aa8).

  • New code comments (your measure, outside /// of .fsi files and test source strings) go from 44 lines / 3936 characters to 6 lines / 310 characters. What is left are the four one-line docs of the new RelatedSymbolUseKind cases and two issue links. The intent that comments carried moved into names: linesBeforeText, tripleSlashLength, tryFindFirstXmlLine, trySingleLineValueSpan, allAsCompiledIntoOlderCallers (the mask a caller compiled against the old All still passes), CapturedRelatedSymbolUsesInCode, addLambdaBinders.
  • Two comments were also wrong and are gone: one said batch compilation builds no candidates (signature vals do), the other that XmlDocRef.Text is the value "as written" (entities are decoded).
  • Nothing in the PR consumed the cref kind, so XmlDocRefKind.Cref, the scan of see, seealso, exception and permission, their test rows and five baseline lines are removed. GetRefs returns the name values of param, paramref, typeparam and typeparamref only.
  • The 28 test methods are 8: labelled theory rows with every scenario kept (30 before, 30 after), and one extractRefs in FSharp.Test.Utilities replaces the two near-duplicate {ref} scanners.
  • The release notes say what a caller sees; the Visual Studio entry is one line.

The diff is +681/-38 (it was +866/-37). FSharp.Compiler.Service.Tests (SurfaceArea, XmlDocRefs, XmlDocTests, Symbols, EditorTests: 310 tests) and the component tests FindReferences, SemanticClassificationRegressions and XmlComments (136) pass locally. The implicit type parameter case from your last review is fixed in d907d5d, see the thread.

xperiandri added a commit to xperiandri/fsharp that referenced this pull request Oct 29, 2026
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>

@T-Gro T-Gro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 🕵️ Re-reviewed all recent changes as of 97c3e2c; LGTM

Comment thread src/Compiler/Checking/NameResolution.fs Resolved
Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
Comment thread src/Compiler/SyntaxTree/XmlDoc.fs Resolved
@xperiandri
xperiandri force-pushed the fix/xmldoc-param-symbol-uses branch from 97c3e2c to ba04f9f Compare November 5, 2026 18:17
xperiandri added a commit to xperiandri/fsharp that referenced this pull request Nov 5, 2026
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>
xperiandri added a commit to xperiandri/fsharp that referenced this pull request Nov 5, 2026
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>

@xperiandri xperiandri Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't it possible to mark [<Struct>] here too?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we add an overload and deprecate the other?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@xperiandri
xperiandri requested a review from T-Gro November 5, 2026 19:58
xperiandri added a commit to xperiandri/fsharp that referenced this pull request Nov 5, 2026
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>
xperiandri added a commit to xperiandri/fsharp that referenced this pull request Nov 5, 2026
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 T-Gro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖🕵️ 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[]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖🕵️ 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)

xperiandri and others added 11 commits November 8, 2026 03:04
`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>
@xperiandri
xperiandri force-pushed the fix/xmldoc-param-symbol-uses branch from e8223ff to 210f47d Compare November 8, 2026 03:18

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

⚠️ Affects-Agent-Config Tooling check: PR modifies AI agent instructions or workflows ⚠️ Affects-Design-Time Tooling check: PR touches type providers or dependency manager AI-reviewed PR reviewed by AI review council

Projects

Status: In Progress

Development

Successfully merging this pull request may close these issues.

Have PreXmlDoc/XmlDoc track names and ranges for param/paramref children

3 participants