Report XML doc parameter names as related symbol uses by xperiandri · Pull Request #20637 · dotnet/fsharp

xperiandri · 2026-09-26T01:38:07Z

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 its name and cref attribute values 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

`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>

github-actions · 2026-09-26T01:38:17Z

✅ Release notes checked

✅ Found changes and release notes in following paths:

Change path Release notes path Description

`src/Compiler` docs/release-notes/.FSharp.Compiler.Service/11.0.200.md

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

xperiandri · 2026-09-26T01:38:53Z

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

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)

Attribute substring matching misidentifies XML attributes · New
Multiline XML tags are not scanned correctly · New

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

xperiandri · 2026-09-26T10:34:27Z

+        let rec find i =
+            match text.IndexOf(attribute, i, StringComparison.Ordinal) with
+            | -1 -> ValueNone
+            | at when at >= close -> ValueNone
+            | at ->
+                let mutable j = at + attribute.Length
+


Confirmed: <param notname="wrong" name="x"> reported wrong. The scanner now walks each tag's attributes as tokens and compares whole names, which also keeps a > inside a quoted value from ending the tag. Covered by only a whole attribute name matches, and a quoted > does not end the tag. Fixed in 008cb20.

xperiandri · 2026-09-26T10:34:29Z

+    let scan (lines: string[]) (lineRanges: range[]) =
+        [|
+            for i in 0 .. lines.Length - 1 do
+                let text = lines[i]
+                let m = lineRanges[i]


Confirmed: a name on the line after <param was missed. The whole comment is now scanned as one text and each value is mapped back to its /// line. A value that itself runs over a line break has no single-line range, so it is still skipped. Covered by a tag whose attributes run over several lines and a value that runs over a line break yields nothing. Fixed in 008cb20.

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>

github-actions · 2026-09-26T17:33:59Z

🔍 Tooling Safety Check — Affects-Design-Time
Affects-Design-Time: Editor-service changes affect IDE behavior.

Generated by PR Tooling Safety Check · gpt56 685K · ◷

Copilot AI lite review requested due to automatic review settings September 26, 2026 01:38

xperiandri requested a review from a team as a code owner September 26, 2026 01:38

github-project-automation Bot added this to F# Compiler and Tooling Sep 26, 2026

Copilot started reviewing on behalf of xperiandri September 26, 2026 01:38 View session

Add release note for XML doc parameter symbol uses

22d091a

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

xperiandri mentioned this pull request Sep 26, 2026

Renaming a parameter does not update <param>, <paramref>, <typeparam> and <typeparamref> in its XML doc #20630

Open

Copilot AI reviewed Sep 26, 2026

View reviewed changes

xperiandri mentioned this pull request Sep 26, 2026

Rename a parameter together with its XML doc param tags #20638

Open

github-actions Bot added the ⚠️ Affects-Design-Time Tooling check: PR touches type providers or dependency manager label Sep 26, 2026

This comment has been minimized.

Sign in to view

xperiandri mentioned this pull request Sep 26, 2026

Resolve <see cref> in XML doc comments like C# #20640

Open

Navigation Menu

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

Report XML doc parameter names as related symbol uses#20637
xperiandri wants to merge 3 commits into
dotnet:mainfrom
xperiandri:fix/xmldoc-param-symbol-uses

xperiandri commented Sep 26, 2026

Uh oh!

github-actions Bot commented Sep 26, 2026 •

edited

Loading

Uh oh!

xperiandri commented Sep 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

xperiandri Sep 26, 2026

Uh oh!

xperiandri Sep 26, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions Bot commented Sep 26, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

xperiandri commented Sep 26, 2026

Uh oh!

github-actions Bot commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Release notes checked

Uh oh!

xperiandri commented Sep 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

xperiandri Sep 26, 2026

Choose a reason for hiding this comment

Uh oh!

xperiandri Sep 26, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions Bot commented Sep 26, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Sep 26, 2026 •

edited

Loading