Fix constructor XML docs, add operator page support, wire MSBuild Api…#16
Merged
Conversation
…MarkApiHeaders Gap 1 - Constructor summary/params ignored (DotNetGenerator): - BuildMethodId: map IL '.ctor' to '#ctor' so the XML doc lookup matches the compiler-generated member ID format - Add tests: ConstructorWithXmlSummary_WritesSummaryToMemberPage, ConstructorWithXmlParams_WritesParamDescriptionsToMemberPage - Link new tests to ApiMarkDotNet-DotNetGenerator-ReadXmlDocumentationComments Gap 2 - Operators absent from generated docs (DotNetGenerator): - IsSpecialNameNonConstructor: exclude op_* from the special-name filter so operator methods reach GetVisibleMembers - Add IsOperator, GetOperatorCSharpName, GetOperatorSymbol, and BuildOperatorSignature helpers for readable C# operator display - BuildMethodSignature and GetMethodGroupName dispatch to operator helpers for correct signatures and display names - WriteTypePage: separate operators before the collision-detection loop; emit an Operators section linking to operators.md - Add WriteTypeOperatorsPage (mirrors C++ WriteClassOperatorsPage) - Add operators row to the api.md file naming convention table - Add OperatorsClass fixture with documented constructor and two operators - Add tests: CreatesOperatorsPage, TypePageHasOperatorsSection, OperatorsPageContainsSummaries, OperatorsPageUsesSymbolHeadings - Add requirement ApiMarkDotNet-DotNetGenerator-DocumentOperatorOverloads at unit and system level with full test coverage Gap 3 - ApiMarkApiHeaders not wired in MSBuild targets: - Add ApiMarkApiHeaders property to ApiMarkTask invocation in targets file - Add ForwardApiHeaders to system-level requirement children list - Add acceptance criterion and test scenario to verification doc Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR closes multiple documentation-generation gaps across the .NET generator and the MSBuild integration by fixing constructor XML doc lookup, adding first-class operator overload documentation (via a per-type operators.md page), and wiring ApiMarkApiHeaders through the MSBuild targets. It also updates fixtures/tests plus requirement/verification docs to reflect and validate the new behavior.
Changes:
- Fix constructor XML doc member ID generation by mapping IL
.ctorto XML-doc#ctor, with regression tests for constructor summaries and parameter docs. - Add operator overload documentation: exclude
op_*methods from the special-name filter, generate a per-typeoperators.mdpage, and link it from the type page (with tests + fixture). - Wire
ApiMarkApiHeadersinto the MSBuild target invocation and update reqstream/verification docs accordingly.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| test/ApiMark.DotNet.Tests/DotNetGeneratorTests.cs | Adds regression/unit tests for constructor XML docs and operator pages. |
| test/ApiMark.DotNet.Fixtures/OperatorsClass.cs | Adds a fixture type containing documented ctor + operator overloads. |
| src/ApiMark.MSBuild/build/DemaConsulting.ApiMark.MSBuild.targets | Forwards ApiMarkApiHeaders into ApiMarkTask. |
| src/ApiMark.DotNet/DotNetGenerator.cs | Implements constructor #ctor doc ID mapping and operator-page generation/signatures. |
| docs/verification/api-mark-msbuild.md | Documents/validates ApiMarkApiHeaders forwarding behavior (formatting needs fix). |
| docs/verification/api-mark-dot-net/dot-net-generator.md | Documents/validates constructor XML docs + operator overload behavior (formatting needs fix). |
| docs/reqstream/api-mark-msbuild.yaml | Adds ForwardApiHeaders requirement under MSBuild task requirements. |
| docs/reqstream/api-mark-dot-net/dot-net-generator.yaml | Adds requirements/tests for constructor XML docs + operator overload documentation. |
| docs/reqstream/api-mark-dot-net.yaml | Links operator overload documentation requirement into the overall .NET reqstream. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix BuildMethodId to append ~ReturnType suffix for op_Implicit/op_Explicit so conversion operator XML doc summaries are correctly resolved - Add parameter-type tie-breaker to operator ordering for deterministic output - Rename OperatorsClass fixture to OperatorsStruct to match project conventions - Restore dropped bold headings in api-mark-msbuild.md and dot-net-generator.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add implicit operator double and explicit operator int to OperatorsStruct fixture with full XML documentation - Add TypeWithConversionOperators_OperatorsPageContainsSummaries test: verifies the ~ReturnType XML doc ID suffix resolves conversion operator summaries onto the operators page - Add TypeWithConversionOperators_OperatorsPageUsesConversionSyntax test: verifies headings use 'implicit operator T' / 'explicit operator T' syntax rather than op_Implicit / op_Explicit IL names - Extend DocumentOperatorOverloads requirement justification to call out the ~ReturnType suffix behaviour and link both new tests - Add conversion operator scenario to verification doc Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add GetVisibleNestedTypes helper to DotNetGenerator; WriteTypePage now
emits a Nested Types section and recursively writes nested type pages at
{NamespacePath}/{TypeName}/{NestedTypeName}.md, matching the C++ pattern
- Add 'Nested type' row to the api.md convention table
- Fix BuildMethodId: apply Replace('/','.') to ReturnType.FullName in the
~ReturnType suffix for op_Implicit/op_Explicit so conversion operators
returning nested types resolve XML doc summaries correctly
- Add OuterClass fixture with public nested Inner class (both documented)
- Add Wrapped nested struct and implicit operator Wrapped to OperatorsStruct
to exercise the ~ReturnType normalization with a nested return type
- Add 4 tests: NestedClass_CreatesNestedClassPage,
NestedClass_ListedOnOuterClassPage, NestedClass_PageContainsSummary,
ConversionOperatorReturningNestedType_OperatorsPageContainsSummary
- Add ApiMarkDotNet-DotNetGenerator-DocumentNestedTypes requirement
- Link nested-return-type test to DocumentOperatorOverloads requirement
- Add 3 verification scenarios for nested types and ~ReturnType normalization
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jun 15, 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.
…MarkApiHeaders
Gap 1 - Constructor summary/params ignored (DotNetGenerator):
Gap 2 - Operators absent from generated docs (DotNetGenerator):
Gap 3 - ApiMarkApiHeaders not wired in MSBuild targets: