Add configurable output formats, example blocks, and generator refactor

.cspell.yaml

@@ -15,9 +15,12 @@ words:
   - ApiMark
   - buildmark
   - Cecil
+  - cref
+  - crefs
   - csproj
   - cstddef
   - declspec
+  - deletedmembersclass
   - Dema
   - dllexport
   - docstrings
@@ -26,8 +29,10 @@ words:
   - ANTLR
   - GHDL
   - hrefs
+  - invocability
   - isysroot
   - isystem
+  - langword
   - libc
   - libclang
   - libclangsharp
@@ -36,18 +41,23 @@ words:
   - Linkification
   - Linkify
   - linkify
+  - Linq
   - misattributed
   - msbuild
   - MSBuild
   - msvc
   - mylib
   - MYLIB
+  - nameof
+  - testlib
   - NDEBUG
   - netstandard
   - Pandoc
   - parameterless
+  - paramref
   - pasteable
   - postconditions
+  - repoint
   - reqstream
   - reviewmark
   - runtimeconfig
@@ -61,8 +71,10 @@ words:
   - subclassable
   - constexpr
   - cppreference
+  - endcode
   - fparse
   - fsyntax
+  - unparseable
   - versionmark
   - writability
   - VHDL

.gitattributes

@@ -0,0 +1,7 @@
+# Set default behavior: normalize line endings to LF on checkout for all text files.
+# This ensures consistent SHA256 fingerprints for reviewmark across all platforms.
+* text=auto eol=lf
+
+# Windows batch files require CRLF line endings to function correctly.
+*.bat text eol=crlf
+*.cmd text eol=crlf

.gitignore

@@ -29,6 +29,11 @@ node_modules/
 # Generated compliance documents (build outputs — never committed)
 **/generated/
 
+# Generated API documentation output (written by ApiMark; never committed)
+**/api-gradual/
+**/api-single/
+**/api/
+
 # Agent logs
 .agent-logs/
 

.markdownlint-cli2.yaml

@@ -11,6 +11,9 @@ ignores:
   - '**/3rd-party/**'
   - '**/generated/**'
   - '**/.agent-logs/**'
+  - '**/bin/**'
+  - test/ApiMark.Cpp.Fixtures/api-gradual/**
+  - test/ApiMark.Cpp.Fixtures/api-single/**
 config:
   # Require ATX-style headers
   MD003:

.reviewmark.yaml

@@ -66,6 +66,26 @@ reviews:
       - src/ApiMark.Core/IApiGenerator.cs
       - test/ApiMark.Core.Tests/IApiGeneratorTests.cs
 
+  # ApiMarkCore - IApiEmitter
+  - id: ApiMark-Core-IApiEmitter
+    title: Review that ApiMark Core IApiEmitter Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-core/i-api-emitter.yaml
+      - docs/design/api-mark-core/i-api-emitter.md
+      - docs/verification/api-mark-core/i-api-emitter.md
+      - src/ApiMark.Core/IApiEmitter.cs
+      - test/ApiMark.Core.Tests/IApiGeneratorTests.cs
+
+  # ApiMarkCore - EmitConfig
+  - id: ApiMark-Core-EmitConfig
+    title: Review that ApiMark Core EmitConfig Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-core/emit-config.yaml
+      - docs/design/api-mark-core/emit-config.md
+      - docs/verification/api-mark-core/emit-config.md
+      - src/ApiMark.Core/EmitConfig.cs
+      - src/ApiMark.Core/OutputFormat.cs
+
   # ApiMarkCore - IContext
   - id: ApiMark-Core-IContext
     title: Review that ApiMark Core IContext Implementation is Correct
@@ -136,22 +156,82 @@ reviews:
       - docs/verification/api-mark-dot-net.md
       - docs/verification/api-mark-dot-net/**/*.md
 
-  # ApiMarkDotNet - Generator
-  - id: ApiMark-DotNet-Generator
-    title: Review that ApiMark DotNet Generator Implementation is Correct
+  # ApiMarkDotNet - DotNetGenerator
+  - id: ApiMark-DotNet-DotNetGenerator
+    title: Review that ApiMark DotNet DotNetGenerator Implementation is Correct
     paths:
       - docs/reqstream/api-mark-dot-net/dot-net-generator.yaml
       - docs/design/api-mark-dot-net/dot-net-generator.md
       - docs/verification/api-mark-dot-net/dot-net-generator.md
       - src/ApiMark.DotNet/ApiVisibility.cs
       - src/ApiMark.DotNet/DotNetGenerator.cs
       - src/ApiMark.DotNet/DotNetGeneratorOptions.cs
-      - src/ApiMark.DotNet/XmlDocReader.cs
-      - test/ApiMark.DotNet.Fixtures/**/*.cs
       - test/ApiMark.DotNet.Tests/DotNetGeneratorTests.cs
-      - test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs
       - test/ApiMark.DotNet.Tests/FixturePaths.cs
 
+  # ApiMarkDotNet - DotNetAstModel
+  - id: ApiMark-DotNet-DotNetAstModel
+    title: Review that ApiMark DotNet DotNetAstModel Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/dot-net-ast-model.yaml
+      - docs/design/api-mark-dot-net/dot-net-ast-model.md
+      - docs/verification/api-mark-dot-net/dot-net-ast-model.md
+      - src/ApiMark.DotNet/DotNetAstModel.cs
+      - test/ApiMark.DotNet.Tests/DotNetAstModelTests.cs
+
+  # ApiMarkDotNet - DotNetEmitter
+  - id: ApiMark-DotNet-DotNetEmitter
+    title: Review that ApiMark DotNet DotNetEmitter Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/dot-net-emitter.yaml
+      - docs/design/api-mark-dot-net/dot-net-emitter.md
+      - docs/verification/api-mark-dot-net/dot-net-emitter.md
+      - src/ApiMark.DotNet/DotNetEmitter.cs
+      - test/ApiMark.DotNet.Tests/DotNetEmitterTests.cs
+
+  # ApiMarkDotNet - DotNetEmitterGradualDisclosure
+  - id: ApiMark-DotNet-DotNetEmitterGradualDisclosure
+    title: Review that ApiMark DotNet DotNetEmitterGradualDisclosure Implementation
+      is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/dot-net-emitter-gradual-disclosure.yaml
+      - docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md
+      - docs/verification/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md
+      - src/ApiMark.DotNet/DotNetEmitterGradualDisclosure.cs
+      - test/ApiMark.DotNet.Fixtures/**/*.cs
+      - test/ApiMark.DotNet.Tests/DotNetEmitterGradualDisclosureTests.cs
+
+  # ApiMarkDotNet - DotNetEmitterSingleFile
+  - id: ApiMark-DotNet-DotNetEmitterSingleFile
+    title: Review that ApiMark DotNet DotNetEmitterSingleFile Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/dot-net-emitter-single-file.yaml
+      - docs/design/api-mark-dot-net/dot-net-emitter-single-file.md
+      - docs/verification/api-mark-dot-net/dot-net-emitter-single-file.md
+      - src/ApiMark.DotNet/DotNetEmitterSingleFile.cs
+      - test/ApiMark.DotNet.Fixtures/**/*.cs
+      - test/ApiMark.DotNet.Tests/DotNetEmitterSingleFileTests.cs
+
+  # ApiMarkDotNet - XmlDocReader
+  - id: ApiMark-DotNet-XmlDocReader
+    title: Review that ApiMark DotNet XmlDocReader Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml
+      - docs/design/api-mark-dot-net/xml-doc-reader.md
+      - docs/verification/api-mark-dot-net/xml-doc-reader.md
+      - src/ApiMark.DotNet/XmlDocReader.cs
+      - test/ApiMark.DotNet.Tests/XmlDocReaderTests.cs
+
+  # ApiMarkDotNet - TypeLinkResolver
+  - id: ApiMark-DotNet-TypeLinkResolver
+    title: Review that ApiMark DotNet TypeLinkResolver Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-dot-net/type-link-resolver.yaml
+      - docs/design/api-mark-dot-net/type-link-resolver.md
+      - docs/verification/api-mark-dot-net/type-link-resolver.md
+      - src/ApiMark.DotNet/TypeLinkResolver.cs
+      - test/ApiMark.DotNet.Tests/TypeLinkResolverTests.cs
+
   # ApiMarkDotNet - TypeNameSimplifier
   - id: ApiMark-DotNet-TypeNameSimplifier
     title: Review that ApiMark DotNet TypeNameSimplifier Implementation is Correct
@@ -185,22 +265,80 @@ reviews:
       - docs/verification/api-mark-cpp.md
       - docs/verification/api-mark-cpp/**/*.md
 
-  # ApiMarkCpp - Generator
-  - id: ApiMark-Cpp-Generator
-    title: Review that ApiMark Cpp Generator Implementation is Correct
+  # ApiMarkCpp - CppGenerator
+  - id: ApiMark-Cpp-CppGenerator
+    title: Review that ApiMark Cpp CppGenerator Implementation is Correct
     paths:
       - docs/reqstream/api-mark-cpp/cpp-generator.yaml
       - docs/design/api-mark-cpp/cpp-generator.md
-      - docs/design/api-mark-cpp/clang-ast-parser.md
       - docs/verification/api-mark-cpp/cpp-generator.md
       - src/ApiMark.Cpp/ApiVisibility.cs
       - src/ApiMark.Cpp/CppGenerator.cs
       - src/ApiMark.Cpp/CppGeneratorOptions.cs
+      - test/ApiMark.Cpp.Tests/CppGeneratorTests.cs
+      - test/ApiMark.Cpp.Tests/FixturePaths.cs
+
+  # ApiMarkCpp - CppAstModel
+  - id: ApiMark-Cpp-CppAstModel
+    title: Review that ApiMark Cpp CppAstModel Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/cpp-ast-model.yaml
+      - docs/design/api-mark-cpp/cpp-ast-model.md
+      - docs/verification/api-mark-cpp/cpp-ast-model.md
       - src/ApiMark.Cpp/CppAst/CppAstModel.cs
+      - test/ApiMark.Cpp.Tests/CppAstModelTests.cs
+
+  # ApiMarkCpp - ClangAstParser
+  - id: ApiMark-Cpp-ClangAstParser
+    title: Review that ApiMark Cpp ClangAstParser Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/clang-ast-parser.yaml
+      - docs/design/api-mark-cpp/clang-ast-parser.md
+      - docs/verification/api-mark-cpp/clang-ast-parser.md
       - src/ApiMark.Cpp/CppAst/ClangAstParser.cs
       - test/ApiMark.Cpp.Fixtures/**/*.h
-      - test/ApiMark.Cpp.Tests/CppGeneratorTests.cs
-      - test/ApiMark.Cpp.Tests/FixturePaths.cs
+      - test/ApiMark.Cpp.Tests/ClangAstParserTests.cs
+
+  # ApiMarkCpp - CppEmitter
+  - id: ApiMark-Cpp-CppEmitter
+    title: Review that ApiMark Cpp CppEmitter Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/cpp-emitter.yaml
+      - docs/design/api-mark-cpp/cpp-emitter.md
+      - docs/verification/api-mark-cpp/cpp-emitter.md
+      - src/ApiMark.Cpp/CppEmitter.cs
+      - test/ApiMark.Cpp.Tests/CppEmitterTests.cs
+
+  # ApiMarkCpp - CppEmitterGradualDisclosure
+  - id: ApiMark-Cpp-CppEmitterGradualDisclosure
+    title: Review that ApiMark Cpp CppEmitterGradualDisclosure Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/cpp-emitter-gradual-disclosure.yaml
+      - docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md
+      - docs/verification/api-mark-cpp/cpp-emitter-gradual-disclosure.md
+      - src/ApiMark.Cpp/CppEmitterGradualDisclosure.cs
+      - test/ApiMark.Cpp.Fixtures/**/*.h
+      - test/ApiMark.Cpp.Tests/CppEmitterGradualDisclosureTests.cs
+
+  # ApiMarkCpp - CppEmitterSingleFile
+  - id: ApiMark-Cpp-CppEmitterSingleFile
+    title: Review that ApiMark Cpp CppEmitterSingleFile Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/cpp-emitter-single-file.yaml
+      - docs/design/api-mark-cpp/cpp-emitter-single-file.md
+      - docs/verification/api-mark-cpp/cpp-emitter-single-file.md
+      - src/ApiMark.Cpp/CppEmitterSingleFile.cs
+      - test/ApiMark.Cpp.Tests/CppEmitterSingleFileTests.cs
+
+  # ApiMarkCpp - CppTypeLinkResolver
+  - id: ApiMark-Cpp-CppTypeLinkResolver
+    title: Review that ApiMark Cpp CppTypeLinkResolver Implementation is Correct
+    paths:
+      - docs/reqstream/api-mark-cpp/cpp-type-link-resolver.yaml
+      - docs/design/api-mark-cpp/cpp-type-link-resolver.md
+      - docs/verification/api-mark-cpp/cpp-type-link-resolver.md
+      - src/ApiMark.Cpp/CppTypeLinkResolver.cs
+      - test/ApiMark.Cpp.Tests/CppTypeLinkResolverTests.cs
 
   # ApiMarkMSBuild - Specials
   - id: ApiMark-MSBuild-Architecture
@@ -317,3 +455,15 @@ reviews:
       - docs/reqstream/ots/clang.yaml
       - docs/design/ots/clang.md
       - docs/verification/ots/clang.md
+  - id: OTS-DemaConsultingTestResults
+    title: Review that DemaConsulting.TestResults Provides Required Functionality
+    paths:
+      - docs/reqstream/ots/dema-consulting-test-results.yaml
+      - docs/design/ots/dema-consulting-test-results.md
+      - docs/verification/ots/dema-consulting-test-results.md
+  - id: OTS-CppAstNet
+    title: Review that CppAst.Net Archived OTS Artifacts are Complete
+    paths:
+      - docs/reqstream/ots/cpp-ast-net.yaml
+      - docs/design/ots/cpp-ast-net.md
+      - docs/verification/ots/cpp-ast-net.md

README.md

@@ -24,6 +24,8 @@ type page — consuming only as much context as the task requires.
 
 - 📄 **Compact Markdown Output** - AI-friendly API reference from source code
 - 🔍 **Gradual Disclosure** - Index → namespace → type → member detail
+- 🗂️ **Multiple Output Formats** - Gradual-disclosure (file-per-type) or single `api.md` via `--format`
+- 💡 **Example Code Blocks** - `<example><code>` (C#) and `@code`/`@endcode` (Doxygen) blocks rendered in output
 - 🔷 **C#/.NET Support** - Mono.Cecil + XML documentation comments
 - ➕ **C++ Support** - `clang -ast-dump=json` + Doxygen-style comments
 - 🔧 **MSBuild Integration** - Auto-documents `.csproj` and `.vcxproj` builds
@@ -101,9 +103,15 @@ for full control over what gets passed to clang.
 # Generate API documentation from a .NET assembly
 apimark dotnet --assembly MyProject.dll --xml-doc MyProject.xml --output docs/api
 
+# Generate a single-file API reference
+apimark dotnet --assembly MyProject.dll --xml-doc MyProject.xml --output docs/api --format single-file
+
 # Generate API documentation from C++ public headers (document all headers under include/)
 apimark cpp --includes include/ --output docs/api
 
+# Generate a single-file C++ API reference
+apimark cpp --includes include/ --output docs/api --format single-file
+
 # Document only specific headers using --api-headers patterns (gitignore-style, ordered)
 apimark cpp \
   --includes include/ \