Repository navigation
Fix record EqualityContract, GeneratedRegex, field-like-event, and Warning-severity doc-coverage issues - #50
Merged
Malcolmnixon merged 3 commits intoOct 7, 2026
Conversation
… members - Exclude a record's compiler-generated EqualityContract property from both --enforce-docs coverage checking and Markdown emission (sealed, non-sealed, and derived records), while still reporting a hand-written property of the same name. - Accept a <remarks> as documentation (in addition to <summary>) for members carrying [GeneratedCodeAttribute], so [GeneratedRegex] partial methods whose XML doc summary is overwritten by the source generator no longer fail --enforce-docs. - Exclude a field-like event's compiler-generated backing field (detected via CompilerGeneratedAttribute, since it shares the event's exact name) from both coverage checking and emission, when the event itself is documented. - Elevate --enforce-docs findings logged by ApiMarkTask to real MSBuild warnings/errors (via the new LogToolOutputLine), based on ApiMarkEnforceDocsSeverity, instead of only low-visibility informational messages invisible at normal build verbosity. Adds fixtures and tests for all four scenarios, and updates the design, reqstream, and verification documentation for the affected units (DotNetEmitter, DocumentationCoverageChecker, ApiMarkTask) accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Address the generated-type documentation fallback and make the backing-field regression test exercise the intended code path.
Review effort: Lite
Findings: 2
Open (2)
What changed in this PR
This PR fixes documentation false positives for compiler-generated .NET members and improves MSBuild enforcement visibility.
Changes:
- Filters generated record properties and event backing fields.
- Accepts generated-code remarks during coverage checks.
- Elevates enforcement findings to configured MSBuild warning/error severity.
- Adds fixtures, tests, and documentation updates.
| File | Summary |
|---|---|
test/ApiMark.MSBuild.Tests/ApiMarkTaskTests.cs |
Tests MSBuild severity logging. |
test/ApiMark.DotNet.Tests/DotNetEmitterTests.cs |
Tests generated-member filtering. |
test/ApiMark.DotNet.Tests/DocumentationCoverageCheckerTests.cs |
Tests coverage behavior. |
test/ApiMark.DotNet.Fixtures/RecordClass.cs |
Adds record fixtures. |
test/ApiMark.DotNet.Fixtures/GeneratedRegexClass.cs |
Adds generated-regex fixture. |
test/ApiMark.DotNet.Fixtures/FieldLikeEventClass.cs |
Adds field-like event fixture. |
src/ApiMark.MSBuild/ApiMarkTask.cs |
Elevates enforcement findings. |
src/ApiMark.DotNet/DotNetEmitter.cs |
Filters generated properties and fields. |
src/ApiMark.DotNet/DocumentationCoverageChecker.cs |
Updates coverage rules. |
docs/verification/api-mark-msbuild/api-mark-task.md |
Documents MSBuild verification. |
docs/verification/api-mark-dot-net/dot-net-emitter.md |
Documents emitter verification. |
docs/verification/api-mark-dot-net/documentation-coverage-checker.md |
Documents coverage verification. |
docs/reqstream/api-mark-msbuild/api-mark-task.yaml |
Updates MSBuild requirements. |
docs/reqstream/api-mark-dot-net/documentation-coverage-checker.yaml |
Updates coverage requirements. |
docs/design/api-mark-msbuild/api-mark-task.md |
Documents logging behavior. |
docs/design/api-mark-dot-net/dot-net-emitter.md |
Documents generated-member filtering. |
docs/design/api-mark-dot-net/documentation-coverage-checker.md |
Documents coverage rules. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- Restrict the GeneratedCodeAttribute <remarks> documentation fallback to members only, not types: HasDocumentation now explicitly excludes TypeDefinition from the fallback, so a generated public type with no <summary> is still reported as undocumented, matching the intent that the fallback is for generated members (e.g. [GeneratedRegex] methods), not generated types. - Fix Check_DocumentedFieldLikeEvent_DoesNotReportBackingField to check at ApiVisibility.All instead of Public, since the private backing field was previously filtered out by visibility before IsCompilerGeneratedField was ever consulted, making the regression test a false pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Three requirements added during formal-review remediation were not linked into the system-level requirement tree, making them orphaned (unreachable from any requirement tagged quality/system): - ApiMarkDotNet-DocumentationCoverageChecker-ExcludeCompilerGeneratedMembers - ApiMarkDotNet-DocumentationCoverageChecker-AcceptRemarksForGeneratedCodeMembers - ApiMarkMsbuild-ApiMarkTask-ElevateUndocumentedFindings Added them as children of their respective parent system requirements (ApiMarkDotNet-EnforceDocumentationCoverage and ApiMarkMsbuild-ApiMarkTask-IntegrateWithMsbuild). `dotnet reqstream --lint` and the full `lint.ps1` pass now run clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Malcolmnixon
deleted the
fix/record-equalitycontract-doc-coverage-false-positives
branch
October 7, 2026 11:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes four related
--enforce-docs/ Markdown-emission false positives, allstemming from compiler-generated members that have no source location to
attach documentation to, plus one build-visibility issue:
EqualityContractproperty reported as undocumented and givenits own Markdown page/table row, for every C#
recordtype (sealed,non-sealed, and derived). Fixed by excluding compiler-generated properties
from both
DocumentationCoverageCheckerandDotNetEmitter, the same waycompiler-generated methods were already excluded. A hand-written property
named
EqualityContracton a normal class is still reported/emitted.[GeneratedRegex]methods losing their<summary>to the regexsource generator's own
<remarks>in the compiled XML doc, making thempermanently fail
--enforce-docs. Fixed by accepting a non-empty<remarks>as documentation for members carrying[GeneratedCodeAttribute]— coverage-checking only; Markdown emission is unchanged.
the event itself is documented. Fixed by also excluding fields carrying
[CompilerGeneratedAttribute](the backing field shares the event's exactname, so the existing angle-bracket name check didn't catch it).
--enforce-docsfindings invisible in normal MSBuildoutput — they were logged as plain messages, so builds reported
"0 Warning(s)" and findings only appeared at
-v n. Fixed by elevating[Undocumented]finding lines to realLog.LogWarning/Log.LogErrorcalls based on
ApiMarkEnforceDocsSeverity.Testing
RecordClass.cs,FieldLikeEventClass.cs,GeneratedRegexClass.cs) and unit tests covering all four scenarios acrossDotNetEmitterTests,DocumentationCoverageCheckerTests, andApiMarkTaskTests.affected units (
DotNetEmitter,DocumentationCoverageChecker,ApiMarkTask).(
ApiMark-MSBuild-Task,ApiMark-DotNet-DotNetEmitter,ApiMark-DotNet-DocumentationCoverageChecker).fix.ps1/lint.ps1run clean.Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com