Enhance XML doc rendering for NamespaceDoc and list elements

[Malcolmnixon]

This pull request significantly enhances namespace-level documentation in the API Markdown generator by extracting and emitting <remarks> and <example> content from NamespaceDoc carrier classes, not just <summary>. It also introduces support for rendering XML <list> elements as Markdown lists or tables, and updates the data model and requirements to reflect these capabilities.

Namespace documentation improvements:

• NamespaceDoc carrier classes now have their <remarks> and <example> content extracted and included in the namespace description dictionary, alongside <summary>. This ensures that all authored namespace documentation is available for output. [1] [2] [3] [4]
• The DotNetAstModel data structure replaces the namespace description value from a single summary string to a NamespaceDescription record, bundling summary, remarks, and structured example parts. [1] [2] [3]
• Both gradual-disclosure and single-file emitters now output namespace remarks and example parts after the summary, mirroring the type-level rendering. [1] [2] [3] [4] [5]

XML documentation rendering enhancements:

• The XML doc reader now supports rendering <list> elements (of type bullet, number, or table) as proper Markdown lists or tables, preserving the structure and formatting intended by the author. [1] [2] [3]

Requirements and documentation updates:

• Requirement streams and YAML documentation are updated to specify and test the new behaviors for extracting namespace remarks/examples and rendering XML lists. [1] [2] [3] [4] [5] [6] [7]

These changes ensure that namespace documentation is comprehensive and that XML documentation features are faithfully represented in the generated Markdown.

[Copilot]

Pull request overview

Enhances ApiMark’s .NET XML documentation pipeline by (1) promoting full namespace-level documentation from NamespaceDoc carrier types (summary + remarks + structured examples) into the parsed model and emitted Markdown, and (2) rendering XML <list> elements into Markdown list/table equivalents.

Changes:

• Extend XmlDocReader to render <list type="bullet|number|table"> into Markdown (including term/description formatting and table cell escaping).
• Replace namespace description strings with a structured NamespaceDescription model, and emit summary/remarks/examples for namespaces in both gradual-disclosure and single-file formats.
• Add fixtures, tests, and update design/verification/reqstream/user-guide docs to specify and validate the new behaviors.

Reviewed changes

Copilot reviewed 28 out of 28 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs	Adds unit coverage for <list> rendering in <remarks> (bullet/number/table, escaping, nesting, spacing).
test/ApiMark.DotNet.Tests/DotNetGeneratorTests.cs	Adds end-to-end generator tests for NamespaceDoc remarks/examples and list rendering through emit.
test/ApiMark.DotNet.Tests/DotNetEmitterSingleFileTests.cs	Verifies single-file emitter outputs namespace remarks/examples and renders list tables.
test/ApiMark.DotNet.Tests/DotNetEmitterGradualDisclosureTests.cs	Verifies gradual-disclosure emitter outputs namespace remarks/examples and renders numbered lists.
test/ApiMark.DotNet.Fixtures/NamespaceDoc.cs	Extends NamespaceDoc fixture with <remarks> and <example><code>.
test/ApiMark.DotNet.Fixtures/ListDocClass.cs	Introduces fixture types containing <list> XML in remarks for integration testing.
src/ApiMark.DotNet/XmlDocReader.cs	Implements <list> element rendering to Markdown and integrates it into XML doc text dispatch.
src/ApiMark.DotNet/DotNetGenerator.cs	Extracts namespace summary/remarks/examples from NamespaceDoc carriers into a NamespaceDescription.
src/ApiMark.DotNet/DotNetEmitterSingleFile.cs	Emits namespace summary, remarks, and structured example parts in single-file output.
src/ApiMark.DotNet/DotNetEmitterGradualDisclosure.cs	Emits namespace summary, remarks, and structured example parts in namespace pages and uses summary in index tables.
src/ApiMark.DotNet/DotNetAstModel.cs	Adds NamespaceDescription record and updates model/context types to use it.
docs/verification/api-mark-dot-net/xml-doc-reader.md	Updates verification claims and scenarios for <list> rendering.
docs/verification/api-mark-dot-net/type-link-resolver.md	Updates verification bullets/scenarios (nullable/array behaviors) for the resolver doc.
docs/verification/api-mark-dot-net/dot-net-generator.md	Updates verification bullets/scenarios for NamespaceDoc remarks/examples and list rendering.
docs/verification/api-mark-dot-net/dot-net-emitter-single-file.md	Updates verification bullets/scenarios for namespace remarks/examples and list-table output.
docs/verification/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md	Updates verification bullets/scenarios for namespace remarks/examples and numbered-list output.
docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml	Adds requirement coverage for rendering <list> elements as Markdown.
docs/reqstream/api-mark-dot-net/dot-net-generator.yaml	Adds requirement coverage for extracting NamespaceDoc remarks/examples.
docs/reqstream/api-mark-dot-net/dot-net-emitter-single-file.yaml	Adds requirement coverage for emitting NamespaceDoc remarks/examples in single-file output.
docs/reqstream/api-mark-dot-net/dot-net-emitter-gradual-disclosure.yaml	Adds requirement coverage for emitting NamespaceDoc remarks/examples in gradual-disclosure output.
docs/reqstream/api-mark-dot-net.yaml	Wires new requirement IDs into the root .NET reqstream index.
docs/design/api-mark-dot-net/xml-doc-reader.md	Documents the new <list> rendering rules and limitations in the XML doc reader design.
docs/design/api-mark-dot-net/dot-net-generator.md	Documents the new namespace doc extraction into NamespaceDescription.
docs/design/api-mark-dot-net/dot-net-emitter-single-file.md	Documents namespace remarks/examples emission order in single-file output.
docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md	Documents namespace remarks/examples emission order in gradual-disclosure output.
docs/design/api-mark-dot-net/dot-net-ast-model.md	Documents the new NamespaceDescription record and updated NamespaceDescriptions shape.
docs/design/api-mark-dot-net.md	Updates high-level design overview to mention NamespaceDoc remarks/examples promotion.
docs/user_guide/dotnet.md	Updates user guide for NamespaceDoc capabilities and documents <list> support.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.