microsoft / microsoft/microsoft-ui-reactor

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

Open Beginner friendly
#1,053 2 comments 0 reactions 0 assignees View on GitHub
bug needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.