microsoft / microsoft/microsoft-ui-reactor
[Bug] One malformed XML doc comment silently disables *all* XML-doc diagnostics repo-wide (CS1574/CS1591 never computed)
- Dominant language
- C#
- Stars
- 646
- Forks
- 54
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 84
Description
### What happened?
`tests/Reactor.Tests/TaskbarOverlayTests.cs:9` contains a bare `&` inside a doc comment:
```csharp
/// Spec 036 §11.2 — 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 `` to ``.
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 `cref`s 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 `CS1574`s, 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
```text
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
- [x] I have searched existing issues and this isn't a duplicate.
- [x] This bug reproduces against the current `main` branch.
Contributor guide
Research direction
Start at tests/Reactor.Tests/TaskbarOverlayTests.cs:9, where the malformed XML doc comment is identified. Replace the bare ampersand with the escaped form, then run the documented dotnet build command with GenerateDocumentationFile=true. Done means the build emits CS1574 and other XML-documentation diagnostics instead of silently reporting only CS1570.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- build-system, testing
- Issue type
- Bug
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100