Rename a parameter together with its XML doc param tags by xperiandri · Pull Request #20638 · dotnet/fsharp

xperiandri · 2026-09-26T02:08:48Z

Fixes #20630
Stacked on #20637

Renaming a parameter or type parameter in Visual Studio left <param name="x">, <paramref>, <typeparam> and <typeparamref> in the declaration's /// comment untouched. Rename now asks the checker for every related use, so the names #20637 reports inside the comment are rewritten together with the parameter, as C# does; a name on a /// line gets the bare text — U for 'U, a b for ``a b``. Document highlights show the tag name when the caret is on the parameter.

Find All References and the refactorings that collect uses pass the new SymbolHelpers.codeSymbolUseKinds, which leaves the doc names out, so a reference list stays code-only.

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

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

Rename asks for every related use, so the `<param>`, `<paramref>`, `<typeparam>` and `<typeparamref>` names the checker now reports are rewritten with the parameter; a name inside a `///` line gets the bare text, without the type-parameter tick or backticks. Find All References passes `SymbolHelpers.codeSymbolUseKinds`, which leaves the doc names out, and document highlights keep showing them. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-09-26T02:09:00Z

✅ Release notes checked

✅ Found changes and release notes in following paths:

Warning

No PR link found in some release notes, please consider adding it.

Change path Release notes path Description

`src/Compiler` docs/release-notes/.FSharp.Compiler.Service/11.0.200.md No current pull request URL (#20638) found, please consider adding it

`vsintegration/src` docs/release-notes/.VisualStudio/18.vNext.md

xperiandri · 2026-09-26T02:09:05Z

Covered cases, driven through InlineRenameService end to end (FSharp.Editor.Tests/InlineRenameXmlDocTests.fs, each compares the rewritten document text):

<param> and <paramref> of a let-bound function
<typeparam> and <typeparamref>: 'T → 'U writes name="U"
rename to ``the addend`` writes name="the addend"
<param> of a member, this untouched
<param> of a primary constructor, documented on the type

DocumentHighlightsServiceTests: the caret on x highlights the name="x" of its <param> alongside the code uses. FindReferencesTests: Find All References on a documented parameter reports the body use only.

Swapping the two masks (rename with codeSymbolUseKinds, Find All References with All) fails the five rename tests and the Find All References one.

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

Copilot

Copilot review overview

🟡 Changes recommended

Unresolved moderate issues remain in XML-doc scanning and rename paths.

Review effort: Lite
Findings: 2

Open (2)

Require XML attribute name token boundaries · New
Include XML parameter uses in project-scope renames · New

What changed in this PR

Adds XML documentation parameter/type-parameter references to rename and highlighting while excluding them from Find All References.

Changes:

Tracks and reports XML-doc references.
Updates rename, highlighting, and filtering behavior.
Adds compiler/editor tests and release notes.

File	Description
`vsintegration/tests/FSharp.Editor.Tests/InlineRenameXmlDocTests.fs`	XML-doc rename tests
`vsintegration/tests/FSharp.Editor.Tests/FSharp.Editor.Tests.fsproj`	Test project updates
`vsintegration/tests/FSharp.Editor.Tests/FindReferencesTests.fs`	Reference filtering tests
`vsintegration/tests/FSharp.Editor.Tests/DocumentHighlightsServiceTests.fs`	Documentation highlighting tests
`vsintegration/src/FSharp.Editor/Navigation/FindUsagesService.fs`	Excludes documentation uses
`vsintegration/src/FSharp.Editor/LanguageService/SymbolHelpers.fs`	Adds use-kind filtering
`vsintegration/src/FSharp.Editor/InlineRename/InlineRenameService.fs`	Applies doc-aware rename edits
`tests/FSharp.Compiler.Service.Tests/XmlDocTests.fs`	XML-doc scanner 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-doc API declarations
`src/Compiler/SyntaxTree/XmlDoc.fs`	XML-doc 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 indexed documentation uses
`src/Compiler/Checking/RelatedSymbolUse.fs`	Adds XML-doc use kind
`src/Compiler/Checking/NameResolution.fsi`	Declares documentation-use reporting
`src/Compiler/Checking/NameResolution.fs`	Reports matching documentation references
`src/Compiler/Checking/Expressions/CheckExpressions.fs`	Reports function parameter references
`src/Compiler/Checking/CheckIncrementalClasses.fs`	Reports constructor references
`src/Compiler/Checking/CheckDeclarations.fs`	Reports declaration and union-field references
`docs/release-notes/.VisualStudio/18.vNext.md`	Documents editor behavior
`docs/release-notes/.FSharp.Compiler.Service/11.0.200.md`	Documents FCS API behavior

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

xperiandri · 2026-09-26T10:43:22Z

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


Confirmed. This code comes from #20637 and is fixed there in 008cb20; it is brought into this branch as 2139ae0. The scanner now walks attributes as tokens, compares whole names, and scans the whole comment, so a tag that runs over several /// lines is found too.

xperiandri · 2026-09-26T10:43:24Z

+    // Rename follows a parameter into its `<param>`/`<typeparam>` tags, which Find All References leaves out
    let symbolUses =
-        SymbolHelpers.getSymbolUsesInSolution (symbolUse, checkFileResults, document) ct
+        SymbolHelpers.getSymbolUsesInSolution (symbolUse, checkFileResults, document, RelatedSymbolUseKind.All) ct


Confirmed. A public union case field is the one symbol with a <param> tag that takes the project-wide path, and the index behind that path deliberately leaves doc names out. When the caller asks for XmlDocParameter, findSymbolUses now also reads the doc uses from the check results of the files that declare the symbol (declaration and signature), keeping only ranges that are not already code uses. Added param of a public union case field follows the field; it fails without the lookup. Fixed in a605e28.

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>

A public union case field is found through the project-wide index, which leaves out names inside `///` comments, so renaming it left its `<param>` tag behind. When the caller asks for XML doc uses, they are now read from the check results of the files that declare the symbol, next to the index results. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Recognizing a `///` line copied the whole line into a string for every rename location; it now reads the characters from the source text. The tag text no longer goes through an intermediate `TrimStart` copy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

github-actions · 2026-09-27T04:45:50Z

🔍 Tooling Safety Check — Affects-Build-Infra, Affects-Design-Time, Affects-Restore
Affects-Build-Infra: Build projects, scripts, or targets are modified.
Affects-Design-Time: Compiler-service or IDE design-time behavior changes.
Affects-Restore: Package references, feeds, or restore inputs change.

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

xperiandri and others added 3 commits September 26, 2026 03:22

Add release note for XML doc parameter symbol uses

22d091a

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

Copilot AI lite review requested due to automatic review settings September 26, 2026 02:08

xperiandri requested a review from a team as a code owner September 26, 2026 02:08

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

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

Add release note for renaming XML doc param tags

e9a9b86

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

Copilot started reviewing on behalf of xperiandri September 26, 2026 02:09 View session

Copilot AI reviewed Sep 26, 2026

View reviewed changes

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

xperiandri and others added 3 commits September 26, 2026 12:34

This comment has been minimized.

Sign in to view

github-actions Bot added ⚠️ Affects-Build-Infra Tooling check: PR touches build infrastructure ⚠️ Affects-Restore Tooling check: PR touches NuGet packages or feeds labels Sep 26, 2026

This comment has been minimized.

Sign in to view

Navigation Menu

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

Rename a parameter together with its XML doc param tags#20638
xperiandri wants to merge 7 commits into
dotnet:mainfrom
xperiandri:fix/rename-xmldoc-param-tags

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.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions Bot commented Sep 27, 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.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions Bot commented Sep 27, 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