[Bug] One malformed XML doc comment silently disables *all* XML-doc diagnostics repo-wide (CS1574/CS1591 never computed)

[azchohfi]

What happened?

tests/Reactor.Tests/TaskbarOverlayTests.cs:9 contains a bare & inside a doc comment:

/// Spec 036 §11.2 — <see cref="TaskbarOverlay"/> setter & dispose-guard

That is invalid XML, so the compiler reports CS1570. The surprise is what happens next: Roslyn abandons the XML documentation pass for the entire compilation, so every other doc diagnostic — CS1574 (unresolved cref), CS1591 (missing doc on a public member), CS1573, CS1580 — is never computed for any file in that project.

Expected: CS1570 is reported alongside the other doc diagnostics.
Actual: CS1570 is reported instead of them, and the build output is indistinguishable from a project whose doc comments are all clean.

This is not a shipping-code defect — GenerateDocumentationFile is off in normal builds, so nothing is broken today. It is a verification defect, and it is the expensive kind: the standard way to check "did I write a bad cref?" is

dotnet build tests/Reactor.Tests -c Release -p:Platform=x64 -p:SkipSignaturesGen=true -p:GenerateDocumentationFile=true

and on main today that command returns zero CS1574 for every file in the project, forever, regardless of what is in them. A confident zero from a check that never ran — exactly the class AGENTS.md § Checks that actually prove something is about, and the reason this is worth a one-character fix rather than a note.

Steps to reproduce

Measured on main @ 1ed2644e7d98e310f0efb6db4c33c5f0ec2f2568. The seeded bad cref is the positive control; without it the experiment cannot distinguish "clean" from "never ran".

1. Seed a deliberately-unresolvable cref anywhere in tests/Reactor.Tests, e.g. change some <see cref="Something"/> to <see cref="ZzzNoSuchMemberAnywhere"/>.

2. Build with doc generation on:

   dotnet build tests/Reactor.Tests -c Release -p:Platform=x64 \
     -p:SkipSignaturesGen=true -p:CopilotSkipCliDownload=true \
     -p:GenerateDocumentationFile=true --no-dependencies
   

   Result — the control is invisible:

   ZzzNoSuchMemberAnywhere mentions in build output : 0
   CS1574 mentions                                  : 0
   Build FAILED.  0 Warning(s)  1 Error(s)
     TaskbarOverlayTests.cs(9,58): error CS1570: XML comment has badly formed XML
   

3. Change that one & to & and rebuild, changing nothing else:

   ZzzNoSuchMemberAnywhere mentions : 2
   CS1574 mentions                  : 28
   Build FAILED.  0 Warning(s)  11173 Error(s)
   

   (Error(s) rather than Warning(s) because Directory.Build.props:67 sets TreatWarningsAsErrors in Release. The 11,173 are overwhelmingly CS1591 on samples/** sources compiled into the test project — expected, and not the point.)

4. Remove the seeded cref, keep the &, rebuild: 13 unique CS1574, all pre-existing, spread across GridSizeTests.cs (3), DataPageCacheParityTests.cs, DevtoolsSerializationTests.cs, DockingGlobalsCollection.cs, GalleryActivationRouting.cs, GalleryPackageIdentity.cs, HotReloadStateMigrationTests.cs, KeyedListDiffPoolingTests.cs, TestIsolationCollections.cs, ToggleSwitchPortTests.cs, V1OnRegistrationTests.cs.

Step 4 is the payoff: those 13 broken crefs have been invisible to the obvious check for as long as the & has been there.

Suggested fix

1. TaskbarOverlayTests.cs:9 — & → & (one character; unblocks the diagnostic pass).
2. Optionally fix the 13 now-visible CS1574s, or NoWarn them deliberately so the suppression is a decision on the record rather than a side effect of malformed XML in an unrelated file.

Worth considering separately: because the failure mode is global and silent, any future CS1570 re-arms it. A cheap guard is a doc-generating build in CI (or a mur check rule) that asserts the count of emitted doc diagnostics is non-zero — i.e. treats "no doc diagnostics at all" as evidence the pass did not run, not as a clean bill of health.

Reactor version / commit

1ed2644e7d98e310f0efb6db4c33c5f0ec2f2568 (origin/main)

Platform

x64

.NET SDK version

10.0.302

Windows version

Windows 11 (build 22631)

Windows App SDK version

As resolved by the repo's Directory.Packages.props — not relevant to this defect (compile-time only).

Logs / stack trace

Before (bare & present, seeded bad cref present):
  TaskbarOverlayTests.cs(9,58): error CS1570: XML comment has badly formed XML -- 'Whitespace is not allowed at this location.'
  Build FAILED.  0 Warning(s)  1 Error(s)
  -> CS1574 = 0, seeded control = 0

After (& -> &, same seeded bad cref):
  Build FAILED.  0 Warning(s)  11173 Error(s)
  -> CS1574 = 28, seeded control = 2 mentions

Confirmation

• I have searched existing issues and this isn't a duplicate.
• This bug reproduces against the current main branch.

[azchohfi]

Corroborating measurement from a different compilation, which supports the body's mechanism and bounds the title's scope claim — plus a default-build consequence worth adding to the context.

The blast radius is per-compilation, not repo-wide

The body is precise — "Roslyn abandons the XML documentation pass for the entire compilation" — but the title generalises that to repo-wide, which the evidence doesn't support and which matters for anyone triaging this.

Measured on a branch off 1ed2644e, seeding an unresolvable cref into two projects at once and building in one pass:

ARM A  src/Reactor.Advanced  (GenerateDocumentationFile=true in the csproj)
       -> CS1574 fired, 2 hits
          DataGridState.cs(8,16): warning CS1574: XML comment has cref attribute
          'ZzBrokenCrefControl_DoesNotExist' that could not be resolved

ARM B  tests/Reactor.Tests    (doc-gen not set; plain build, NO -p:GenerateDocumentationFile)
       -> 0 hits, build exit 0

ARM A firing is the load-bearing part: the malformed & at TaskbarOverlayTests.cs:9 lives in tests/Reactor.Tests, and the doc pass in src/Reactor.Advanced is healthy and emitting in the same build. So the three doc-gen-on product libraries (src/Reactor, src/Reactor.Advanced, src/Reactor.Devtools) are not poisoned by it. The defect is real and the suggested one-character fix is right; the scope is one compilation.

That's also a useful positive control for anyone re-running the repro: if ARM A stops firing, the cause is in Reactor.Advanced itself, not in the test project.

The default-build consequence, which I'd add to the framing

The body notes "GenerateDocumentationFile is off in normal builds, so nothing is broken today" and classifies this as a verification-only defect. Agreed on shipping impact — but there's a second consequence that bites authors rather than verifiers:

GenerateDocumentationFile is true for exactly three projects, all under src/, and no test project. So on every ordinary build and every CI run, a <see cref="..."/> written inside a test file is never resolved:

<see cref> in a test file is inert — and it is the one syntax whose entire purpose is to be machine-checked. That makes it worse than <c>…</c>, which promises nothing. An author writing a breadcrumb comment (/// see <see cref="SomeTest_ThatCoversThis"/>) has every reason to believe the compiler is holding that pointer honest. It isn't, on any build they will normally run.

Combined with this issue's mechanism, the two failure modes stack in the same direction:

build	cref in a test file	why
default	not checked	doc-gen off
-p:GenerateDocumentationFile=true	not checked	this issue — one CS1570 kills the pass

Both silent, both green. That's the argument for the suggested CI guard asserting a non-zero doc-diagnostic count — it's the only proposal here that fails loudly in both rows.

Also relevant to the cross-assembly case

A breadcrumb pointing from product code at a test (e.g. DataGridState.cs → a [Fact] in DataGridPerfCacheTests.cs) cannot use cref at all — the product assembly doesn't reference the test assembly, so the cref would itself be unresolvable and warn. <c>…</c> there is forced, not sloppy. So across both directions there is currently no working compiler instrument for test-referencing breadcrumbs, which is worth knowing before relying on one.

Method notes: both arms injected in a single build so they share compiler state; ARM A is the positive control and the ARM B zero is only interpretable because ARM A fired; tree restored in a finally and verified dirty 0 afterwards. Nothing here changes the suggested fix — one character at TaskbarOverlayTests.cs:9 — I'm only narrowing the scope claim and adding the author-facing half.

[azchohfi]

Adjacent measurement: GenerateDocumentationFile is set in exactly three projects, which makes any future IDE0005 opt-in asymmetric

Found while verifying an unrelated claim that an unused using would fail Release builds. It doesn't — but
the reason routes through the same property this issue is about, so recording it here rather than opening a
near-duplicate.

OBSERVED_AT 2026-08-01T16:17Z    main = 1ed2644e

GenerateDocumentationFile = true:
  src/Reactor/Reactor.csproj:48
  src/Reactor.Advanced/Reactor.Advanced.csproj:42
  src/Reactor.Devtools/Reactor.Devtools.csproj:35
  -> no test project sets it

IDE0005 / CS8019 severity in any .editorconfig / .props / .targets:  0 occurrences repo-wide
TreatWarningsAsErrors: Directory.Build.props:66-68, Condition="'$(Configuration)' == 'Release'"

Roslyn states the coupling itself when you try to escalate the rule without the property:

error EnableGenerateDocumentationFile: Set MSBuild property 'GenerateDocumentationFile' to 'true' to enable IDE0005 (Remove unnecessary usings/imports) on build

The consequence, which is latent rather than live

Nothing is broken today: no severity is configured, so IDE0005 never fires anywhere.

But the day someone adds dotnet_diagnostic.IDE0005.severity = error to a root .editorconfig, it
activates in exactly those three src/ projects and stays silent in every test project — an asymmetric
activation produced by a single global setting, and invisible to whoever adds the line.

That is the same shape as this issue's finding one level out: a diagnostic's reach is gated by a
per-project property, so a repo-wide-looking configuration change lands on a subset. Worth keeping
together, since a fix here (enforcing or documenting GenerateDocumentationFile coverage) would also make
that future opt-in behave the way its author expects.

A related pair of claims, for anyone reading this thread later

• A green Release build is not evidence that there are no unused usings. The rule was never activated,
  so the build is silent about it. (Within one run, "nothing to report" and "never executed" are
  byte-identical — the same trap as a static reviewer that never posts an empty review.)
• The general practice is sound and already tracked in [Docs] AGENTS.md field notes should warn that a green Debug build doesn't clear Build solution (Release-only TreatWarningsAsErrors) #991 — build -c Release, because
  TreatWarningsAsErrors is Release-scoped and a green Debug build does not clear Build solution. That
  holds for genuinely-emitted warnings (CS0162, xUnit2020 were real catches on open PRs today). It
  simply cannot reach a diagnostic that is never emitted at all.