Repository navigation
Enhance API documentation coverage enforcement for .NET, C++, and VHDL - #36
Merged
Merged
Conversation
Adds --enforce-docs/--enforce-docs-severity CLI flags, ApiMarkEnforceDocs/ApiMarkEnforceDocsSeverity MSBuild properties, and a new DocumentationCoverageChecker unit in ApiMark.DotNet, with supporting design/requirements/verification docs and tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Extends the --enforce-docs / --enforce-docs-severity documentation coverage enforcement feature (previously .NET-only) to C++ (full parity with .NET) and VHDL (public-interface-only: entities, ports, generics, packages, and package exports; architecture-internal signals/processes/functions are explicitly deferred). - Add shared IDocumentationCoverageCapable interface and DocumentationCoverageResult in ApiMark.Core, replacing the DotNet-specific downcast in Program.cs with polymorphic dispatch. - Add DocumentationCoverageChecker implementations for Cpp and Vhdl. - Wire cpp/vhdl enforcement options through CppGenerator, VhdlGenerator, ApiMarkTask, and the MSBuild .targets file. - Fix CppGenerator to reject invalid/numeric visibility values instead of silently defaulting to Public, and to clear the namespace declaration cache on parse failure. - Update design, requirements, verification, SysML2, and user guide documentation for all affected units across Core, Cpp, DotNet, MSBuild, Tool, and Vhdl. - Add unit and package-level tests covering the new behavior. Addresses findings from 26 formal reviews (gpt-5.4-mini) and 2 built-in code reviews of the C++/VHDL extension. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…inux clang test failures Linux clang's -fparse-all-comments flag attaches any comment immediately preceding a declaration (even plain // prose, not just Doxygen ///) as that declaration's FullComment/Summary. UndocumentedKindsFixture.h had explanatory prose comments directly above its intentionally-undocumented declarations, which clang on Linux parsed as genuine doc summaries, causing DocumentationCoverageCheckerTests to report zero undocumented items on Ubuntu CI. Rewrote the fixture so explanatory prose lives in a single file-level comment block, keeping only the two genuine /// @brief comments on intentionally-documented overloads. Verified: all 13 DocumentationCoverageCheckerTests and the full 172-test ApiMark.Cpp.Tests suite pass on Linux (WSL Ubuntu, clang 18.1.3). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- .agent-logs-review-template.md was accidentally committed to the repo root instead of staying as an agent working artifact; it isn't referenced anywhere in the repo. - Shortened the overly long Documentation Coverage Enforcement feature bullet in README.md to a concise one-liner. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds an opt-in documentation coverage enforcement feature across ApiMark’s .NET, C++, and VHDL generators by introducing a shared capability interface (IDocumentationCoverageCapable) and common result model, then wiring it through the CLI (--enforce-docs, --enforce-docs-severity) and MSBuild task/property forwarding so builds can warn or fail when undocumented API surface is detected.
Changes:
- Added a Core capability interface and shared result types for language-agnostic documentation coverage reporting.
- Implemented documentation coverage checkers for .NET, C++, and VHDL, plus CLI dispatch/reporting and MSBuild forwarding.
- Added/updated unit + package integration tests and expanded requirements/design/verification/user-guide documentation to cover the new feature.
Reviewed changes
Copilot reviewed 96 out of 96 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/ApiMark.Vhdl.Tests/Fixtures/undocumented.vhd | New VHDL fixture exercising undocumented declaration kinds and intended scope boundary. |
| test/ApiMark.Vhdl.Tests/DocumentationCoverageCheckerTests.cs | Unit tests for VHDL documentation coverage checking and tier validation behavior. |
| test/ApiMark.Tool.Tests/Cli/ContextTests.cs | Adds CLI parsing tests for --enforce-docs and --enforce-docs-severity. |
| test/ApiMark.MSBuild.Tests/ApiMarkTaskTests.cs | Adds MSBuild task argument-forwarding tests for enforce-docs options (dotnet/cpp). |
| test/ApiMark.MSBuild.PackageTests/PackageIntegrationTests.cs | End-to-end NuGet package wiring test proving MSBuild properties reach the tool and can fail builds. |
| test/ApiMark.MSBuild.PackageTests/Fixtures/DotNet/SampleLibEnforceDocs/SampleLib.csproj | New sample project fixture for enforce-docs MSBuild integration testing. |
| test/ApiMark.MSBuild.PackageTests/Fixtures/DotNet/SampleLibEnforceDocs/SampleClass.cs | Fixture source containing an intentionally undocumented public member. |
| test/ApiMark.MSBuild.PackageTests/ApiMark.MSBuild.PackageTests.csproj | Excludes fixture .cs files from compilation; copies fixtures to output for tests. |
| test/ApiMark.DotNet.Tests/DotNetGeneratorTests.cs | Adds tests covering DotNetGenerator enforce-docs call ordering and configuration errors. |
| test/ApiMark.Cpp.Tests/CppGeneratorTests.cs | Adds coverage for WorkingDirectory null fallback behavior for header patterns. |
| test/ApiMark.Cpp.Fixtures/include/fixtures/UndocumentedKindsFixture.h | New C++ fixture covering all undocumented “kind” cases and overload disambiguation. |
| test/ApiMark.Core.Tests/IDocumentationCoverageCapableTests.cs | Adds Core contract tests for interface invocability and result model derived properties. |
| src/ApiMark.Vhdl/VhdlGeneratorOptions.cs | Adds VHDL enforce-docs tier storage option. |
| src/ApiMark.Vhdl/VhdlGenerator.cs | Implements documentation coverage capability for VHDL and caches parsed models for checking. |
| src/ApiMark.Vhdl/DocumentationCoverageChecker.cs | Adds VHDL coverage scanning logic over parsed public-interface declarations. |
| src/ApiMark.Tool/Program.cs | Adds CLI enforcement dispatch between Parse and Emit; adds reporting + tier validation. |
| src/ApiMark.Tool/Cli/Context.cs | Adds parsed CLI properties for enforce-docs tier and severity. |
| src/ApiMark.MSBuild/build/DemaConsulting.ApiMark.MSBuild.targets | Forwards MSBuild enforce-docs properties into the task invocation. |
| src/ApiMark.MSBuild/ApiMarkTask.cs | Adds MSBuild properties and forwards them as tool CLI arguments for dotnet/cpp. |
| src/ApiMark.DotNet/DotNetGenerator.cs | Implements documentation coverage capability for .NET and introduces an enforcement option. |
| src/ApiMark.DotNet/DocumentationCoverageChecker.cs | Adds .NET coverage scanning logic over Cecil + XML docs with enforcement tier. |
| src/ApiMark.Cpp/DocumentationCoverageChecker.cs | Adds C++ coverage scanning logic over parsed clang AST model with enforcement tier. |
| src/ApiMark.Cpp/CppGeneratorOptions.cs | Adds enforcement tier option for C++ generator. |
| src/ApiMark.Cpp/CppGenerator.cs | Implements documentation coverage capability for C++ and caches parsed namespaces. |
| src/ApiMark.Core/IDocumentationCoverageCapable.cs | Introduces the shared capability interface for coverage enforcement. |
| src/ApiMark.Core/DocumentationCoverageResult.cs | Introduces shared result/violation models for coverage reporting. |
| requirements.yaml | Includes new ReqStream requirement files for coverage enforcement artifacts. |
| README.md | Documents the feature at a high level as a supported capability. |
| docs/verification/introduction.md | Adds verification inventory entries for new coverage checker work. |
| docs/verification/api-mark-vhdl/documentation-coverage-checker.md | New VHDL checker verification document. |
| docs/verification/api-mark-vhdl.md | Updates VHDL verification summary with coverage enforcement scenario. |
| docs/verification/api-mark-tool/program.md | Updates CLI Program verification to include enforcement scenarios. |
| docs/verification/api-mark-tool/cli/context.md | Updates CLI Context verification for new options. |
| docs/verification/api-mark-tool.md | Updates tool-level verification summary for enforcement behavior. |
| docs/verification/api-mark-msbuild/api-mark-task.md | Updates MSBuild task verification for new forwarded properties and wiring proof. |
| docs/verification/api-mark-msbuild.md | Updates MSBuild verification summary to include enforcement forwarding behavior. |
| docs/verification/api-mark-dot-net/dot-net-generator.md | Updates .NET generator verification to include coverage enforcement call-order contract. |
| docs/verification/api-mark-dot-net/documentation-coverage-checker.md | New .NET checker verification document. |
| docs/verification/api-mark-dot-net.md | Updates .NET subsystem verification summary for enforcement capability. |
| docs/verification/api-mark-cpp/documentation-coverage-checker.md | New C++ checker verification document. |
| docs/verification/api-mark-cpp/cpp-generator.md | Updates C++ generator verification to include WorkingDirectory fallback coverage. |
| docs/verification/api-mark-core/i-documentation-coverage-capable.md | New Core capability verification document. |
| docs/verification/api-mark-core.md | Updates Core verification summary to include new interface/result model. |
| docs/user_guide/vhdl.md | Documents VHDL CLI options and enforcement behavior/limitations. |
| docs/user_guide/msbuild.md | Documents MSBuild properties, including enforce-docs properties for dotnet/cpp. |
| docs/user_guide/dotnet.md | Documents dotnet enforcement options, behavior, and MSBuild properties. |
| docs/user_guide/cpp.md | Documents cpp enforcement options, behavior, and MSBuild properties. |
| docs/sysml2/model/api-mark-vhdl/documentation-coverage-checker.sysml | Adds SysML2 part definition for VHDL coverage checker. |
| docs/sysml2/model/api-mark-vhdl.sysml | Wires VHDL coverage checker part into the subsystem model. |
| docs/sysml2/model/api-mark-dot-net/documentation-coverage-checker.sysml | Adds SysML2 part definition for .NET coverage checker. |
| docs/sysml2/model/api-mark-dot-net.sysml | Wires .NET coverage checker part into the subsystem model. |
| docs/sysml2/model/api-mark-cpp/documentation-coverage-checker.sysml | Adds SysML2 part definition for C++ coverage checker. |
| docs/sysml2/model/api-mark-cpp.sysml | Wires C++ coverage checker part into the subsystem model. |
| docs/sysml2/model/api-mark-core/i-documentation-coverage-capable.sysml | Adds SysML2 part definition for Core capability interface. |
| docs/sysml2/model/api-mark-core.sysml | Wires Core capability interface part into the subsystem model. |
| docs/reqstream/api-mark-vhdl/documentation-coverage-checker.yaml | Adds VHDL enforcement requirements and linked tests. |
| docs/reqstream/api-mark-vhdl.yaml | Adds VHDL enforcement requirements to subsystem rollup. |
| docs/reqstream/api-mark-tool/program.yaml | Adds CLI enforcement requirements and linked tests. |
| docs/reqstream/api-mark-tool/cli/context.yaml | Adds CLI parsing requirements for new options and linked tests. |
| docs/reqstream/api-mark-tool/cli.yaml | Includes new CLI parsing requirements in the CLI rollup. |
| docs/reqstream/api-mark-tool.yaml | Includes enforcement requirement in the tool rollup. |
| docs/reqstream/api-mark-msbuild/api-mark-task.yaml | Adds MSBuild task forwarding requirements and linked tests. |
| docs/reqstream/api-mark-msbuild.yaml | Includes forwarding requirement in MSBuild rollup. |
| docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml | Refines XmlDocReader requirement wording (provide member docs). |
| docs/reqstream/api-mark-dot-net/dot-net-generator.yaml | Refines dotnet generator requirement wording and inheritdoc requirement naming. |
| docs/reqstream/api-mark-dot-net/documentation-coverage-checker.yaml | Adds .NET enforcement checker requirements and linked tests. |
| docs/reqstream/api-mark-dot-net.yaml | Includes .NET enforcement requirement in subsystem rollup. |
| docs/reqstream/api-mark-cpp/documentation-coverage-checker.yaml | Adds C++ enforcement checker requirements and linked tests. |
| docs/reqstream/api-mark-cpp/cpp-generator.yaml | Updates C++ generator requirements to include header-pattern/CWD fallback tests. |
| docs/reqstream/api-mark-cpp.yaml | Includes C++ enforcement requirements in subsystem rollup. |
| docs/reqstream/api-mark-core/i-documentation-coverage-capable.yaml | Adds Core enforcement capability requirements and linked tests. |
| docs/reqstream/api-mark-core.yaml | Includes capability interface requirement in Core rollup. |
| docs/design/ots.md | Updates OTS consuming systems section (documents consumers including new checker usage). |
| docs/design/introduction.md | Clarifies template mapping conventions for top-level units and fixture locations. |
| docs/design/api-mark-vhdl/vhdl-generator.md | Updates VHDL generator design to include enforce-docs option and checking method. |
| docs/design/api-mark-vhdl/documentation-coverage-checker.md | New VHDL checker design document. |
| docs/design/api-mark-vhdl.md | Updates VHDL subsystem design to include coverage checker unit and capability interface. |
| docs/design/api-mark-tool/program.md | Updates Program design to cover enforce-docs dispatch and reporting behavior. |
| docs/design/api-mark-tool/cli/context.md | Updates Context design to include enforce-docs properties and parsing semantics. |
| docs/design/api-mark-tool/cli.md | Updates CLI design to include new Context properties/options. |
| docs/design/api-mark-tool.md | Updates tool design to include enforce-docs options and execution flow. |
| docs/design/api-mark-msbuild/api-mark-task.md | Updates MSBuild task design for new properties/forwarding. |
| docs/design/api-mark-msbuild.md | Clarifies package layout description. |
| docs/design/api-mark-dot-net/dot-net-generator.md | Updates .NET generator design with enforce-docs option and checking contract. |
| docs/design/api-mark-dot-net/documentation-coverage-checker.md | New .NET checker design document. |
| docs/design/api-mark-dot-net.md | Updates .NET subsystem design to include checker unit and capability interface. |
| docs/design/api-mark-cpp/documentation-coverage-checker.md | New C++ checker design document. |
| docs/design/api-mark-cpp/cpp-generator.md | Updates C++ generator design with enforce-docs option and checking contract. |
| docs/design/api-mark-cpp.md | Updates C++ subsystem design to include checker unit and capability interface. |
| docs/design/api-mark-core/i-documentation-coverage-capable.md | New Core capability design document describing interface and result shape. |
| docs/design/api-mark-core.md | Updates Core design to include capability interface and shared result types. |
| .reviewmark.yaml | Registers review sets for the new enforcement feature across Core/dotnet/cpp/vhdl. |
| .cspell.yaml | Adds “downcast”/“downcasting” to the dictionary. |
Suppressed comments (3)
src/ApiMark.Tool/Program.cs:340
- Enum.TryParse will accept numeric strings (for example, "999") and produce an undefined DotNetApiVisibility value. Without an Enum.IsDefined guard here, an invalid numeric --enforce-docs tier would be treated as valid and could slip through validation.
src/ApiMark.Tool/Program.cs:351 - Enum.TryParse will accept numeric strings (for example, "999") and produce an undefined CppApiVisibility value. Because this block is intended to validate --enforce-docs before Parse runs, add an Enum.IsDefined check so numeric values are rejected here (instead of being treated as valid and only failing later, or producing undefined behavior).
src/ApiMark.Tool/Program.cs:366 - Enum.TryParse will accept numeric strings (for example, "999") and treat them as a valid DotNetApiVisibility value. For the vhdl subcommand this defeats the intended 'fail fast before Parse' validation, because VhdlGenerator will later reject the value anyway. Add Enum.IsDefined so numeric tiers are rejected here with the same error message.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+216
to
+225
| ApiVisibility visibility; | ||
| if (!string.IsNullOrEmpty(enforceTier)) | ||
| { | ||
| if (!Enum.TryParse(enforceTier, ignoreCase: true, out visibility)) | ||
| { | ||
| throw new ArgumentException( | ||
| $"Invalid --enforce-docs value '{enforceTier}'. " + | ||
| $"Valid values are: {string.Join(", ", Enum.GetNames<ApiVisibility>())}."); | ||
| } | ||
| } |
Comment on lines
+250
to
+255
| if (!Enum.TryParse<EnforcementSeverity>(context.EnforceDocsSeverity, ignoreCase: true, out var severity)) | ||
| { | ||
| throw new ArgumentException( | ||
| $"Invalid --enforce-docs-severity value '{context.EnforceDocsSeverity}'. " + | ||
| $"Valid values are: {string.Join(", ", Enum.GetNames<EnforcementSeverity>())}."); | ||
| } |
This was referenced Sep 14, 2026
This was referenced Sep 21, 2026
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.
This pull request introduces documentation coverage enforcement as an opt-in feature across .NET, C++, and VHDL language generators. It defines a new capability interface,
IDocumentationCoverageCapable, and a shared result type, enabling the CLI (--enforce-docs) and MSBuild integration to warn or fail the build when undocumented API surface is detected. The changes include interface design, data model documentation, and review coverage for the new enforcement logic in all supported languages.Documentation Coverage Enforcement (Core design and interface):
IDocumentationCoverageCapableinterface to ApiMark Core, providing a language-agnostic contract for documentation coverage checks. Implemented by .NET, C++, and VHDL generators, and consumed by the CLI and MSBuild tooling via type checks rather than downcasting. [1] [2] [3]DocumentationCoverageResultandUndocumentedApiItemtypes as shared, immutable result models for reporting undocumented declarations. [1] [2]Language Support and Integration:
Review and Test Coverage:
.reviewmark.yamlreview entries for the implementation and tests of documentation coverage enforcement in .NET, C++, and VHDL, ensuring traceability and review of the new feature across all code and documentation artifacts. [1] [2] [3] [4]User-Facing Documentation:
README.mdto advertise documentation coverage enforcement as a supported feature for .NET, C++, and VHDL.Miscellaneous: