Skip to content

WIP: Deduplicate FSharp.Core XML docs via <include> - #20231

Merged
T-Gro merged 5 commits into
mainfrom
t-gro-fsharpcore-xmldoc-include-dedup
Aug 20, 2026
Merged

WIP: Deduplicate FSharp.Core XML docs via <include>#20231
T-Gro merged 5 commits into
mainfrom
t-gro-fsharpcore-xmldoc-include-dedup

Conversation

@T-Gro

@T-GroT-Gro commented Aug 7, 2026

Copy link
Copy Markdown
Member

Follow-up to #19186 (FS-1341): first in-repo use of the compile-time <include> tag inside FSharp.Core.

Moves 8 repeated /// doc blocks (36 call sites) into shared fragments under src/FSharp.Core/xmldoc/ and replaces each occurrence with a one-line <include>:

  • sort stability/complexity remark — array (12), list (5), seq (5)
  • Parallel.For remark — array (5 identical sites; the genuinely different ones are left alone)
  • dynamic-implementation summaries — resumable (5), tasks (4)

Layout: per-topic files (sort.xml, parallel.xml, dynamic.xml) with element-name keys; callsite reads path="/sort/arrayUnstable/*".

Generated FSharp.Core.xml is unchanged apart from insignificant whitespace — verified canonically identical to the pre-change baseline. No documentation wording changes.

WIP: draft while CI is validated.

@github-actions

github-actionsBot commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

⚠️ Release notes required, but author opted out

Warning

Author opted out of release notes, check is disabled for this pull request.
cc @dotnet/fsharp-team-msft

T-Gro added a commit that referenced this pull request Aug 7, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@T-Gro
T-Groforce-pushed the t-gro-fsharpcore-xmldoc-include-dedup branch from bfddcc7 to 2ad440dCompareAugust 7, 2026 11:51
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@T-Gro
T-Groforce-pushed the t-gro-fsharpcore-xmldoc-include-dedup branch from 2ad440d to adff9a8CompareAugust 7, 2026 12:07
@T-GroT-Gro added the NO_RELEASE_NOTES Label for pull requests which signals, that user opted-out of providing release notes label Aug 7, 2026
@T-Gro
T-Gro requested a review from abonieAugust 7, 2026 12:07
@T-Gro
T-Gro marked this pull request as ready for review August 7, 2026 12:07
@T-Gro
T-Gro requested a review from a team as a code ownerAugust 7, 2026 12:07
@github-actionsgithub-actionsBot added the AI-Tooling-Check-Bypassed Tooling check: non-fork PR, not diff-analyzed label Aug 7, 2026
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@T-Gro
T-Groforce-pushed the t-gro-fsharpcore-xmldoc-include-dedup branch from 1da1e28 to 16d621fCompareAugust 12, 2026 08:11
Comment threadsrc/FSharp.Core/xmldoc/sort.xml
@github-project-automationgithub-project-automationBot moved this from New to In Progress in F# Compiler and ToolingAug 12, 2026
Copilotand others added 2 commits August 13, 2026 18:10
… inputs
Addresses review feedback: the <include> XML doc fragments are now referenced in the project (None + UpToDateCheckInput) so they are tracked as compilation inputs for incremental builds and the up-to-date check.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@T-Gro
T-Gro requested a review from abonieAugust 20, 2026 11:04
@T-Gro
T-Gro enabled auto-merge (squash) August 20, 2026 11:04
@T-Gro
T-Gro merged commit 0ae686c into mainAug 20, 2026
52 checks passed
xperiandri pushed a commit to xperiandri/fsharp that referenced this pull request Aug 20, 2026
* Deduplicate FSharp.Core XML docs via <include>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* Add test asserting no unexpanded <include> in generated FSharp.Core.xml
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* Reference xmldoc/*.xml fragments in FSharp.Core.fsproj as compilation inputs
Addresses review feedback: the <include> XML doc fragments are now referenced in the project (None + UpToDateCheckInput) so they are tracked as compilation inputs for incremental builds and the up-to-date check.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Tomas Grosup <tomas.grosup@microsoft.com>
xperiandri pushed a commit to xperiandri/fsharp that referenced this pull request Aug 20, 2026
* Deduplicate FSharp.Core XML docs via <include>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* Add test asserting no unexpanded <include> in generated FSharp.Core.xml
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* Reference xmldoc/*.xml fragments in FSharp.Core.fsproj as compilation inputs
Addresses review feedback: the <include> XML doc fragments are now referenced in the project (None + UpToDateCheckInput) so they are tracked as compilation inputs for incremental builds and the up-to-date check.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Tomas Grosup <tomas.grosup@microsoft.com>
@T-Gro
T-Gro deleted the t-gro-fsharpcore-xmldoc-include-dedup branch August 21, 2026 11:15
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI-Tooling-Check-BypassedTooling check: non-fork PR, not diff-analyzedNO_RELEASE_NOTESLabel for pull requests which signals, that user opted-out of providing release notes

Projects

Archived in project

Development

Successfully merging this pull request may close these issues.

2 participants

@T-Gro@abonie