Fix constructor XML docs, add operator page support, wire MSBuild Api…

docs/reqstream/api-mark-dot-net.yaml

@@ -17,6 +17,7 @@ sections:
           - ApiMarkDotNet-DotNetGenerator-IncludeObsoleteApisWhenRequested
           - ApiMarkDotNet-DotNetGenerator-EmitDetailPageForEveryMember
           - ApiMarkDotNet-DotNetGenerator-ProduceConsistentOutputFileStructure
+          - ApiMarkDotNet-DotNetGenerator-DocumentOperatorOverloads
         tests:
           - ApiMarkDotNet_Generate_ValidAssemblyAndXml_ProducesMarkdown
       - id: ApiMarkDotNet-TypeNameSimplifier-ProduceReadableTypeNames

docs/reqstream/api-mark-dot-net/dot-net-generator.yaml

@@ -29,6 +29,8 @@ sections:
               available from the XML documentation file produced by the C# compiler.
             tests:
               - DotNetGenerator_ReadXmlComments_SummaryAndRemarks_AppearInMarkdown
+              - DotNetGenerator_Generate_ConstructorWithXmlSummary_WritesSummaryToMemberPage
+              - DotNetGenerator_Generate_ConstructorWithXmlParams_WritesParamDescriptionsToMemberPage
           - id: ApiMarkDotNet-DotNetGenerator-FilterByVisibility
             title: DotNetGenerator shall support ApiVisibility filtering for Public, PublicAndProtected, and All.
             justification: |
@@ -116,3 +118,26 @@ sections:
               without cluttering individual type cells with fully-qualified names.
             tests:
               - DotNetGenerator_Generate_ExternalNonSystemParameterType_EmitsExternalTypesSection
+          - id: ApiMarkDotNet-DotNetGenerator-DocumentOperatorOverloads
+            title: >-
+              DotNetGenerator shall document visible operator overload methods on a single
+              dedicated operators.md page per type, using C# operator symbols as headings.
+            justification: |
+              C# types frequently expose arithmetic, comparison, and conversion operators
+              as part of their public API. Operators cannot be given individual pages using
+              their IL names (op_Addition, op_Subtraction, etc.) without ambiguity on
+              case-insensitive file systems, and their IL names are not readable to consumers.
+              Grouping all operators for a type onto a single operators.md page with C#
+              symbol headings (operator +, operator -) makes the operator API surface
+              discoverable and navigable without file-name collisions.
+              Conversion operators (op_Implicit, op_Explicit) carry a ~ReturnType suffix in
+              their XML doc member ID (e.g. M:Type.op_Implicit(SourceType)~TargetType); the
+              generator must append this suffix when resolving XML documentation for them so
+              their summaries and parameter descriptions are not silently dropped.
+            tests:
+              - DotNetGenerator_Generate_TypeWithOperators_CreatesOperatorsPage
+              - DotNetGenerator_Generate_TypeWithOperators_TypePageHasOperatorsSection
+              - DotNetGenerator_Generate_TypeWithOperators_OperatorsPageContainsSummaries
+              - DotNetGenerator_Generate_TypeWithOperators_OperatorsPageUsesSymbolHeadings
+              - DotNetGenerator_Generate_TypeWithConversionOperators_OperatorsPageContainsSummaries
+              - DotNetGenerator_Generate_TypeWithConversionOperators_OperatorsPageUsesConversionSyntax

docs/reqstream/api-mark-msbuild.yaml

@@ -21,6 +21,7 @@ sections:
           - ApiMarkMsbuild-ApiMarkTask-ForwardCppDefines
           - ApiMarkMsbuild-ApiMarkTask-ForwardCppStandard
           - ApiMarkMsbuild-ApiMarkTask-SkipWhenCppIncludePathsNotSet
+          - ApiMarkMsbuild-ApiMarkTask-ForwardApiHeaders
         tests:
           - ApiMarkMsbuild_NuGetPackage_DotNetProject_AutoDocumentsOnBuild
       - id: ApiMarkMsbuild-IncludeDocsInNuGetPackage

docs/verification/api-mark-dot-net/dot-net-generator.md

@@ -27,6 +27,10 @@ network dependency, or privileged configuration is needed.
 - Every visible member receives its own dedicated detail page unless case-insensitive file-name
   collisions require combining members onto one page, and the resulting page is linked from the
   type page, making navigation fully deterministic.
+- Constructor XML summary and parameter descriptions are read from the XML documentation file
+  and written to the constructor's member detail page.
+- Operator overload methods are documented on a single per-type `operators.md` page using C#
+  operator symbols as headings; no individual per-operator pages are created.
 - Generated Markdown content matches expected file names, headings, and signatures.
 - Output files follow the naming convention: `api.md` entrypoint, `{Namespace}.md`
   namespace summaries, `{Namespace}/{TypeName}.md` type pages, and
@@ -85,6 +89,30 @@ namespace — root and child — in a single table with a Types column showing t
 for each namespace, giving AI agents a complete navigation map in one read. This scenario is tested
 by `DotNetGenerator_Generate_ApiMd_ListsAllNamespacesWithTypeCount`.
 
+**Constructor XML documentation appears in the constructor detail page**: Verifies that the
+XML summary and parameter descriptions authored for a constructor are read from the XML
+documentation file and emitted onto the constructor's member detail page, confirming the
+`#ctor` doc ID mapping is applied correctly. This scenario is tested by
+`DotNetGenerator_Generate_ConstructorWithXmlSummary_WritesSummaryToMemberPage` and
+`DotNetGenerator_Generate_ConstructorWithXmlParams_WritesParamDescriptionsToMemberPage`.
+
+**Operator overloads produce a shared operators.md page**: Verifies that all operator
+overload methods defined on a type are grouped onto a single `operators.md` page named with
+C# operator symbols as H2 headings, that the type page shows an Operators section linking to
+it, and that no individual per-operator pages are created. This scenario is tested by
+`DotNetGenerator_Generate_TypeWithOperators_CreatesOperatorsPage`,
+`DotNetGenerator_Generate_TypeWithOperators_TypePageHasOperatorsSection`,
+`DotNetGenerator_Generate_TypeWithOperators_OperatorsPageContainsSummaries`, and
+`DotNetGenerator_Generate_TypeWithOperators_OperatorsPageUsesSymbolHeadings`.
+
+**Conversion operator XML documentation appears on the operators page**: Verifies that XML
+summaries authored on `implicit` and `explicit` conversion operators are correctly resolved
+using the `~ReturnType` suffix in the XML doc member ID, and that their headings use C# syntax
+(`implicit operator T` / `explicit operator T`) rather than the raw IL names (`op_Implicit` /
+`op_Explicit`). This scenario is tested by
+`DotNetGenerator_Generate_TypeWithConversionOperators_OperatorsPageContainsSummaries` and
+`DotNetGenerator_Generate_TypeWithConversionOperators_OperatorsPageUsesConversionSyntax`.
+
 **Case-collision class creates a combined page**: Verifies that members whose names differ only by
 case are merged into a single combined detail page on case-insensitive targets. This scenario is
 tested by `DotNetGenerator_Generate_CaseCollisionClass_CreatesCombinedPage`.

docs/verification/api-mark-msbuild.md

@@ -35,6 +35,8 @@ permission is required.
 - For C++ projects, `ApiMarkDefines` semicolons are converted to commas when forwarding as
   `--defines`.
 - For C++ projects, `ApiMarkCppStandard` is forwarded as `--cpp-standard` when set.
+- For C++ projects, each entry in `ApiMarkApiHeaders` is forwarded as a separate `--api-headers`
+  flag in order, with `!`-prefixed exclusion patterns passed verbatim.
 - When `ApiMarkIncludePaths` is empty for a C++ project, the task returns success with no
   side effects.
 
@@ -85,6 +87,12 @@ C++ builds. This scenario is tested by `ApiMarkTask_Cpp_Defines_SemicolonsConver
 passed to the spawned tool as the `--cpp-standard` argument for C++ builds. This scenario is
 tested by `ApiMarkTask_Cpp_CppStandard_ForwardedToTool`.
 
+**C++ api-headers patterns are forwarded as individual flags**: Verifies that each
+semicolon-delimited entry in `ApiMarkApiHeaders` is emitted as its own `--api-headers` flag
+in order, and that `!`-prefixed exclusion patterns are forwarded verbatim so the generator
+can apply last-match-wins gitignore semantics. This scenario is tested by
+`ApiMarkTask_Cpp_ApiHeaders_ForwardedAsIndividualFlags`.
+
 **Empty include paths causes graceful skip for C++ project**: Verifies that when
 `ApiMarkIncludePaths` is not set for a C++ project, the task returns success immediately with no
 side effects and no tool invocation. This scenario is tested by