Skip to content

Remove REACTOR_DOC_002 — it duplicates CS1574 without adding analysis #496

@codemonkeychris

Description

@codemonkeychris

Summary

REACTOR_DOC_002 (XmlDocCrefAnalyzer) duplicates the built-in compiler diagnostic CS1574 ("XML comment has cref attribute that could not be resolved") without adding any analysis on top. It should be removed and replaced with CS1574 configuration on the framework project.

Background

While fixing the doc-analyzer customer-leak in #491, we audited what REACTOR_DOC_001 and REACTOR_DOC_002 actually do beyond the built-in .NET diagnostics:

  • REACTOR_DOC_001 vs CS1591: earns its keep. It specifically requires a <summary> tag (CS1591 accepts any XML doc, even just <remarks>), and applies broader skip rules for overrides, explicit interface implementations, and [GeneratedCode] types that match Reactor''s docs pipeline (spec 041 §10.4). Keep it.

  • REACTOR_DOC_002 vs CS1574: pure re-skin. The whole analyzer body is:

    var symbol = context.SemanticModel.GetSymbolInfo(node, context.CancellationToken).Symbol;
    if (symbol is not null) return;
    context.ReportDiagnostic(Diagnostic.Create(Rule, node.GetLocation(), text));

    That is identical to what CS1574 does internally — same call, same null check, same condition. The analyzer''s own XML doc admits this:

    Roslyn raises CS1574 for the same condition; this analyzer surfaces it under a Reactor code so doc PRs can elevate severity independently.

    The "independent severity" rationale is weak — CS1574 can already be elevated/suppressed per-project via .editorconfig (dotnet_diagnostic.CS1574.severity = error).

Proposed change

  1. Delete src/Reactor.Analyzers.Internal/XmlDocCrefAnalyzer.cs and its tests in tests/Reactor.Tests/AnalyzerTests/XmlDocCrefAnalyzerTests.cs.
  2. Remove the REACTOR_DOC_002 row from src/Reactor.Analyzers.Internal/AnalyzerReleases.Unshipped.md (it never shipped externally).
  3. Remove REACTOR_DOC_002 from Reactor.csproj''s NoWarn list.
  4. Update the Contains("REACTOR_DOC_002", docIds) assertion in tests/Reactor.Tests/AnalyzerTests/AnalyzerPackagingTests.cs (the InternalAnalyzerAssembly_Hosts_DocCoverageRules test).
  5. If we want enforcement equivalent to what REACTOR_DOC_002 was reserved for, add an .editorconfig entry on src/Reactor/ to configure CS1574 severity (currently passes through default warning).
  6. Update spec 041 §10.4 and docs/guide/analyzer-architecture.md / docs/guide/rules-of-reactor.md to remove the REACTOR_DOC_002 references and point at CS1574 (and CS1580, CS1581, CS1584 for the related cref-malformed family if useful).

Out of scope

REACTOR_DOC_001 stays — it provides real value beyond CS1591 (see "Background" above).

Optional follow-up

If we do want a Reactor-specific cref analyzer that earns its keep, it would need to do something CS1574 doesn''t — e.g.:

  • Flag crefs that resolve but point to internal/non-public symbols (real ref-gen failure mode, since the generator emits a relative MD link that won''t exist).
  • Validate <see href="..."> external URLs against an allow-list.
  • Catch crefs that cross [DocCategory(...)] boundaries in ways that produce broken navigation.

That''s a separate spec and is not blocking this cleanup.

Context

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions