Add configurable output formats, example blocks, and generator refactor#20
Merged
Conversation
…ecomposition Phase 1 — Configurable output formats: - Add IApiEmitter interface and EmitConfig/OutputFormat to ApiMark.Core - Refactor IApiGenerator.Generate() to two-stage Parse() -> IApiEmitter.Emit() - Implement gradual-disclosure and single-file emitters for both DotNet and C++ - Add --format flag to CLI (gradual / single-file) - Add ApiMarkFormat property and ApiMarkOutput item group to MSBuild integration - Fix single-file broken intra-assembly links via TypeLinkResolver(generateLinks: false) - Fix C++ single-file: constructor void return, member signatures, operators, nested types Phase 2 — Example code blocks: - C#: wire XmlDocReader.GetExampleParts() into all gradual-disclosure and single-file member and type sections; renders mixed prose/<code> content as paragraphs and fenced csharp blocks - C++: parse VerbatimBlockComment (@code/@Endcode) in ClangAstParser; add Example field to CppDocComment; render fenced cpp blocks in all gradual-disclosure and single-file member locations - Add ExampleDocClass C# and C++ fixtures with example blocks - Add tests for both languages x both output formats (4 new integration tests) - Add 3 new XmlDocReader.GetExampleParts unit tests Refactor — Generator decomposition: - Split DotNetGenerator.cs (was 2345 lines) into DotNetGenerator, DotNetAstModel, DotNetEmitter, DotNetEmitterGradualDisclosure, DotNetEmitterSingleFile - Split CppGenerator.cs (was 2815 lines) into CppGenerator, CppEmitter, CppEmitterGradualDisclosure, CppEmitterSingleFile - ClangAstParser.cs left intact (single responsibility, no clean seam) - Zero behavior change; all 661 tests pass across net8.0/net9.0/net10.0 Documentation: - README: add multiple output formats and example code block feature bullets - CLI reference: add --format option to dotnet and cpp, expand Output Structure section - MSBuild guide: add ApiMarkFormat property, ApiMarkOutput item group documentation - Requirements: update test citations for ReadXmlDocumentationComments, RenderDoxygenDocComments, and EmitSingleFileOutput requirements Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add InternalsVisibleTo(ApiMark.DotNet.Tests) to ApiMark.DotNet.csproj - Add 10 dedicated unit test files (62 new tests): - DotNetAstModelTests, DotNetEmitterTests - DotNetEmitterGradualDisclosureTests, DotNetEmitterSingleFileTests - TypeLinkResolverTests - CppAstModelTests, CppEmitterTests - CppEmitterGradualDisclosureTests, CppEmitterSingleFileTests - ClangAstParserTests - Update docs/design/introduction.md with current software structure - Split .reviewmark.yaml into per-unit review sets (13 sets) - Exclude generated output folders from lint and git tracking (.cspell.yaml, .gitignore, and remove committed api-gradual/api-single) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add CppEmitter.Emit key method entry to Cpp design doc - Add unit test scenario sections to DotNet and Cpp verification docs (25 DotNet scenarios, 35 Cpp scenarios across 10 new test files) - Map all 62 new unit test methods to requirements in reqstream yamls Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Fix 5 code defects: DotNetEmitter field/event accessibility, TypeLinkResolver generic-param nullability, CppEmitterSingleFile operator functions, CppEmitterGradualDisclosure declaration count, XmlDocReader duplicate keys and GetExample empty-string contract - Sweep Generate -> Parse/Emit staleness across 11 docs and test files - Fix orphaned children: links in DotNet, Cpp, MSBuild, and Tool reqstream YAML - Fix --format accepted value (gradual-disclosure -> gradual) in MSBuild and Tool system design docs - Fix H3/H4 -> H1/H2 heading-level drift in DotNet and Cpp combined-member-page design docs and requirements - Fix --depth help text in Program.cs and cli-reference.md - Create 35 new per-unit artifact files: 6 DotNet (req/design/verify x6), 17 Cpp (req/design/verify sets), 3 OTS DemaConsulting.TestResults artifacts - Register cpp-ast-net and DemaConsulting.TestResults OTS items in both introductions, .reviewmark.yaml, and requirements.yaml - Add 14 new unit review-sets to .reviewmark.yaml (DotNet x6, Cpp x6, OTS x2) - Update both introduction.md files: Software Structure, Scope, Companion Artifact Structure for all new units and OTS items - Add --clang-path requirement (ApiMarkTool-Cli-Context-ParseClangPath) with test and children chain registration - Fix various doc inconsistencies: macOS platform table, EmitConfig equality claim, WriteLink description, PathHelpers comments, ClangAstParser error handling, type-name-simplifier callers, MSBuild ApiMarkOutputs direction, OTS MonoCecil consuming units, and many more - Add new tests: IApiEmitterTests, InMemoryMarkdownWriter pipe-escaping, XmlDocReader GetExceptionDetails and null-return cases, TypeLinkResolver Linkify transforms, Context_Create_WithClangPathOption_SetsClangPath - Lint fixes: 11 cspell words, MD060 table separators, markdownlint ignore list for generated fixture output directories Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR evolves ApiMark’s generation pipeline into a two-stage Parse → Emit model and adds a configurable output format (multi-file “gradual disclosure” vs single-file api.md), along with new example-block parsing/rendering support and expanded requirements/verification documentation.
Changes:
- Introduces
IApiEmitter,EmitConfig, andOutputFormat, refactoring generators to return an emitter fromIApiGenerator.Parse()and emit output viaIApiEmitter.Emit(...). - Adds CLI/MSBuild support for
--format/ApiMarkFormat(plus multi-output support via@(ApiMarkOutput)), and updates help/docs accordingly. - Adds/updates tests, fixtures, and documentation to cover single-file output, link suppression in single-file mode, and example block extraction for both .NET XML docs and C++ Doxygen
@codeblocks.
Reviewed changes
Copilot reviewed 153 out of 154 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| test/ApiMark.Tool.Tests/Cli/ContextTests.cs | Adds CLI parsing tests for --format and --clang-path. |
| test/ApiMark.DotNet.Tests/TypeLinkResolverTests.cs | Adds unit tests for TypeLinkResolver behaviors incl. link suppression. |
| test/ApiMark.DotNet.Tests/DotNetEmitterTests.cs | Adds emitter dispatch/format tests and namespace path tests. |
| test/ApiMark.DotNet.Tests/DotNetEmitterSingleFileTests.cs | Adds integration-style tests for single-file .NET output structure. |
| test/ApiMark.DotNet.Tests/DotNetEmitterGradualDisclosureTests.cs | Adds integration-style tests for gradual-disclosure .NET output. |
| test/ApiMark.DotNet.Tests/DotNetAstModelTests.cs | Adds model property tests for the parse stage. |
| test/ApiMark.DotNet.Fixtures/ExampleDocClass.cs | Adds .NET XML <example><code> fixtures. |
| test/ApiMark.Cpp.Tests/CppGeneratorFixture.cs | Updates fixture generation to Parse→Emit and adds single-file factory. |
| test/ApiMark.Cpp.Tests/CppEmitterSingleFileTests.cs | Adds unit tests for C++ single-file output. |
| test/ApiMark.Cpp.Tests/CppEmitterGradualDisclosureTests.cs | Adds unit tests for C++ gradual-disclosure output. |
| test/ApiMark.Cpp.Tests/ClangAstParserTests.cs | Adds clang-dependent parser tests (skippable). |
| test/ApiMark.Cpp.Fixtures/include/fixtures/ExampleDocFixtures.h | Adds Doxygen @code/@endcode example fixture. |
| test/ApiMark.Core.Tests/PathHelpersTests.cs | Minor test clarity update for null segment case. |
| test/ApiMark.Core.Tests/IMarkdownWriterTests.cs | Renames/clarifies contract test and adds pipe-escaping verification for tables. |
| test/ApiMark.Core.Tests/IContextTests.cs | Renames/clarifies context contract test naming/documentation. |
| test/ApiMark.Core.Tests/IApiEmitterTests.cs | Adds contract tests for IApiEmitter format semantics. |
| test/ApiMark.Core.TestHelpers/InMemoryMarkdownWriterFactory.cs | Adds filename validation for in-memory writer creation. |
| test/ApiMark.Core.TestHelpers/InMemoryMarkdownWriter.cs | Deep-copies table row arrays to prevent post-call mutation affecting recorded ops. |
| src/ApiMark.Tool/Program.cs | Switches tool execution to generator.Parse(...).Emit(...), adds --format to help. |
| src/ApiMark.Tool/Cli/Context.cs | Adds Context.Format and --format parsing. |
| src/ApiMark.MSBuild/build/DemaConsulting.ApiMark.MSBuild.targets | Forwards ApiMarkFormat and outputs item group into the task. |
| src/ApiMark.DotNet/TypeLinkResolver.cs | Adds optional link suppression and nullable generic parameter ? handling. |
| src/ApiMark.DotNet/ApiMark.DotNet.csproj | Adds InternalsVisibleTo for ApiMark.DotNet.Tests. |
| src/ApiMark.Cpp/CppAst/CppAstModel.cs | Extends CppDocComment to include Example. |
| src/ApiMark.Cpp/CppAst/ClangAstParser.cs | Extracts verbatim block (@code) into CppDocComment.Example. |
| src/ApiMark.Core/PathHelpers.cs | Adds clarifying comments around null rejection, normalization, and traversal checks. |
| src/ApiMark.Core/OutputFormat.cs | Introduces OutputFormat enum. |
| src/ApiMark.Core/IMarkdownWriter.cs | Clarifies signature vs code block remarks (currently identical rendering). |
| src/ApiMark.Core/IApiGenerator.cs | Refactors interface to Parse(IContext) -> IApiEmitter. |
| src/ApiMark.Core/IApiEmitter.cs | Introduces emit-stage interface contract. |
| src/ApiMark.Core/FileMarkdownWriterFactory.cs | Doc tweaks clarifying whitespace constraints. |
| src/ApiMark.Core/FileMarkdownWriter.cs | Enforces positive heading levels and clarifies code-block delegation docs. |
| src/ApiMark.Core/EmitConfig.cs | Introduces cross-language emit configuration object. |
| requirements.yaml | Adds new reqstream documents for emitter/config and refactored components. |
| README.md | Documents --format and example block support with usage examples. |
| docs/verification/ots/dema-consulting-test-results.md | Adds verification doc for DemaConsulting.TestResults usage. |
| docs/verification/api-mark-tool/program.md | Adds verification scenario text for --api-headers acceptance. |
| docs/verification/api-mark-tool/cli/context.md | Adds scenarios for --format, --clang-path, and include/api-header parsing changes. |
| docs/verification/api-mark-tool.md | Updates tool verification narrative to reference cpp dispatch coverage. |
| docs/verification/api-mark-msbuild.md | Updates MSBuild verification narrative and clarifies known gaps. |
| docs/verification/api-mark-dot-net/type-name-simplifier.md | Fixes test name reference in verification doc. |
| docs/verification/api-mark-dot-net/type-link-resolver.md | Adds new verification doc for TypeLinkResolver. |
| docs/verification/api-mark-dot-net/dot-net-emitter.md | Adds new verification doc for DotNetEmitter. |
| docs/verification/api-mark-dot-net/dot-net-emitter-single-file.md | Adds new verification doc for DotNetEmitterSingleFile. |
| docs/verification/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md | Adds new verification doc for DotNetEmitterGradualDisclosure. |
| docs/verification/api-mark-dot-net/dot-net-ast-model.md | Adds new verification doc for DotNetAstModel. |
| docs/verification/api-mark-dot-net.md | Updates overall .NET verification overview text. |
| docs/verification/api-mark-cpp/cpp-type-link-resolver.md | Adds new verification doc for CppTypeLinkResolver. |
| docs/verification/api-mark-cpp/cpp-emitter.md | Adds new verification doc for CppEmitter. |
| docs/verification/api-mark-cpp/cpp-emitter-single-file.md | Adds new verification doc for CppEmitterSingleFile. |
| docs/verification/api-mark-cpp/cpp-emitter-gradual-disclosure.md | Adds new verification doc for CppEmitterGradualDisclosure. |
| docs/verification/api-mark-cpp/cpp-ast-model.md | Adds new verification doc for CppAstModel. |
| docs/verification/api-mark-cpp/clang-ast-parser.md | Adds new verification doc for ClangAstParser. |
| docs/verification/api-mark-core/i-markdown-writer.md | Updates writer verification to include signature + table pipe escaping. |
| docs/verification/api-mark-core/i-markdown-writer-factory.md | Updates factory verification narrative with file-based tests. |
| docs/verification/api-mark-core/i-context.md | Updates context verification text and adds note on null-message boundary. |
| docs/verification/api-mark-core/i-api-generator.md | Updates generator verification to Parse→Emit contract and new tests. |
| docs/verification/api-mark-core/i-api-emitter.md | Adds new verification doc for IApiEmitter. |
| docs/verification/api-mark-core/emit-config.md | Adds new verification doc for EmitConfig/OutputFormat. |
| docs/user_guide/msbuild-integration.md | Documents ApiMarkFormat and multi-output configuration (ApiMarkOutput). |
| docs/user_guide/cli-reference.md | Documents --format and output-structure specifics for both formats. |
| docs/reqstream/ots/mono-cecil.yaml | Clarifies Cecil requirement wording. |
| docs/reqstream/ots/dema-consulting-test-results.yaml | Adds OTS requirements for DemaConsulting.TestResults. |
| docs/reqstream/ots/clang.yaml | Updates clang discovery requirement text. |
| docs/reqstream/api-mark-tool/self-test/validation.yaml | Refines validation requirements (exit code vs unsupported extensions). |
| docs/reqstream/api-mark-tool/self-test.yaml | Updates self-test requirement wording and child refs. |
| docs/reqstream/api-mark-tool/program.yaml | Updates cpp option list to include --clang-path. |
| docs/reqstream/api-mark-tool/cli/context.yaml | Updates context parsing requirements, adds format/clang-path requirements. |
| docs/reqstream/api-mark-tool/cli.yaml | Updates CLI requirement wording and adds new child requirements. |
| docs/reqstream/api-mark-tool.yaml | Renames top-level requirement id and adjusts wording. |
| docs/reqstream/api-mark-msbuild/api-mark-task.yaml | Adds requirements for forwarding format and supporting outputs item group. |
| docs/reqstream/api-mark-msbuild.yaml | Wires new MSBuild requirements into the top-level set. |
| docs/reqstream/api-mark-dot-net/xml-doc-reader.yaml | Adds unit requirements for XML doc reader indexing + example parsing. |
| docs/reqstream/api-mark-dot-net/type-link-resolver.yaml | Adds unit requirements for .NET type link resolution. |
| docs/reqstream/api-mark-dot-net/dot-net-generator.yaml | Updates generator requirements for examples + single-file output. |
| docs/reqstream/api-mark-dot-net/dot-net-emitter.yaml | Adds unit requirements for emitter dispatch. |
| docs/reqstream/api-mark-dot-net/dot-net-emitter-single-file.yaml | Adds unit requirements for single-file emitter. |
| docs/reqstream/api-mark-dot-net/dot-net-emitter-gradual-disclosure.yaml | Adds unit requirements for gradual-disclosure emitter. |
| docs/reqstream/api-mark-dot-net/dot-net-ast-model.yaml | Adds unit requirements for parsed model object. |
| docs/reqstream/api-mark-dot-net.yaml | Wires new .NET requirements into the top-level set. |
| docs/reqstream/api-mark-cpp/cpp-type-link-resolver.yaml | Adds unit requirements for C++ type link resolver. |
| docs/reqstream/api-mark-cpp/cpp-emitter.yaml | Adds unit requirements for C++ emitter + dispatch. |
| docs/reqstream/api-mark-cpp/cpp-emitter-single-file.yaml | Adds unit requirements for C++ single-file emitter. |
| docs/reqstream/api-mark-cpp/cpp-emitter-gradual-disclosure.yaml | Adds unit requirements for C++ gradual-disclosure emitter. |
| docs/reqstream/api-mark-cpp/cpp-ast-model.yaml | Adds unit requirements for C++ AST model records. |
| docs/reqstream/api-mark-cpp/clang-ast-parser.yaml | Adds unit requirements for clang AST parsing. |
| docs/reqstream/api-mark-cpp.yaml | Wires new C++ requirements into the top-level set. |
| docs/reqstream/api-mark-core/i-api-generator.yaml | Updates core generator contract requirement to Parse. |
| docs/reqstream/api-mark-core/i-api-emitter.yaml | Adds core requirements for emitter interface. |
| docs/reqstream/api-mark-core/emit-config.yaml | Adds core requirements for emit configuration. |
| docs/reqstream/api-mark-core.yaml | Updates core requirements to reflect two-stage Parse+Emit design. |
| docs/design/ots/mono-cecil.md | Updates OTS design to reflect Parse→Emit lifecycle and disposal behavior. |
| docs/design/ots/dema-consulting-test-results.md | Adds OTS design doc for DemaConsulting.TestResults integration. |
| docs/design/ots/clang.md | Updates OTS design doc command-line flags (-x c++). |
| docs/design/api-mark-tool/program.md | Updates tool design to Parse→Emit and format config behavior. |
| docs/design/api-mark-tool/cli/context.md | Updates context design to include output format. |
| docs/design/api-mark-tool/cli.md | Updates CLI design to include new flags and parsing behavior. |
| docs/design/api-mark-tool.md | Updates system design to Parse→Emit + --format/--clang-path. |
| docs/design/api-mark-msbuild/api-mark-task.md | Documents ApiMarkFormat + ApiMarkOutputs item group behavior. |
| docs/design/api-mark-msbuild.md | Updates MSBuild design to include format forwarding and outputs item group. |
| docs/design/api-mark-dot-net/xml-doc-reader.md | Adds design doc for XML doc indexing and example parsing. |
| docs/design/api-mark-dot-net/type-name-simplifier.md | Updates design doc call sites and arity helper descriptions. |
| docs/design/api-mark-dot-net/type-link-resolver.md | Adds design doc for type linkification and link suppression. |
| docs/design/api-mark-dot-net/dot-net-emitter.md | Adds design doc for emitter dispatcher and helpers. |
| docs/design/api-mark-dot-net/dot-net-emitter-single-file.md | Adds design doc for single-file emitter behavior. |
| docs/design/api-mark-dot-net/dot-net-emitter-gradual-disclosure.md | Adds design doc for gradual-disclosure emitter behavior and paths. |
| docs/design/api-mark-dot-net/dot-net-ast-model.md | Adds design doc for the parsed model object and contexts. |
| docs/design/api-mark-cpp/cpp-type-link-resolver.md | Adds design doc for C++ type linkification behavior. |
| docs/design/api-mark-cpp/cpp-emitter.md | Adds design doc for C++ emitter dispatch + helpers. |
| docs/design/api-mark-cpp/cpp-emitter-single-file.md | Adds design doc for C++ single-file emitter behavior. |
| docs/design/api-mark-cpp/cpp-emitter-gradual-disclosure.md | Adds design doc for C++ gradual-disclosure output structure. |
| docs/design/api-mark-cpp/cpp-ast-model.md | Adds design doc for C++ AST model records including Example. |
| docs/design/api-mark-cpp/clang-ast-parser.md | Updates parser design notes (filtering + args ordering + error handling). |
| docs/design/api-mark-core/i-markdown-writer.md | Updates markdown writer design notes for escaping + link description. |
| docs/design/api-mark-core/i-markdown-writer-factory.md | Updates factory design to reflect Emit stage and SafePathCombine. |
| docs/design/api-mark-core/i-context.md | Updates context design references from Generate→Parse. |
| docs/design/api-mark-core/i-api-generator.md | Updates core generator design to Parse→Emit. |
| docs/design/api-mark-core/i-api-emitter.md | Adds core emitter interface design doc. |
| docs/design/api-mark-core/emit-config.md | Adds core emit configuration design doc. |
| .markdownlint-cli2.yaml | Ignores additional build/fixture output directories. |
| .gitignore | Ignores generated API output folders. |
| .gitattributes | Enforces consistent line endings across platforms. |
| .cspell.yaml | Adds new technical terms to spell-check dictionary. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The test assumed operator names are passed to SanitizeFileName as file names, but in practice operators are always routed to operators.md (gradual disclosure) or api.md (single file) - never used as individual file names. The test also failed cross-platform because Path.GetInvalidFileNameChars() returns different sets on Windows vs Linux. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Reject --depth > 3 when --format single-file is used (either order); member headings are at depth+3 so depth > 3 produces invalid ATX headings (> H6) - IsClangAvailable: kill the process tree on 5s timeout instead of leaving it running; avoids zombie processes blocking CI agents - Fix verification/api-mark-dot-net.md: semicolon followed by capital was incorrect; split into two proper sentences Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…eference - docs/design/api-mark-core/emit-config.md: correct HeadingDepth valid range to 1-3 (depth+3 reaches H6 max; CLI enforces this upper bound) - docs/reqstream/api-mark-dot-net/dot-net-generator.yaml: collapse extra spaces after comma in justification text - docs/verification/api-mark-core/i-markdown-writer-factory.md: update stale IApiGenerator.Generate reference to IApiEmitter.Emit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…rt cleanup - src/ApiMark.Cpp/CppAst/ClangAstParser.cs: only capture VerbatimBlockComment nodes whose 'name' is 'code'; other verbatim commands (@verbatim etc.) are not code examples and should not populate CppDocComment.Example - test/ApiMark.Core.Tests/IMarkdownWriterTests.cs: wrap Directory.Delete in try/catch(IOException) so transient file-lock errors on cleanup do not mask a passing assertion Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- api-mark-core.yaml: replace non-existent ApiMarkCore_MarkdownWriterContract_ FileSections_RenderConsistently with InMemoryMarkdownWriter_Write_AllOperations_ RecordsInOrder - validation.yaml: add Validation_Run_WithUnsupportedResultsExtension_ SetsExitCodeToOne to SetExitCodeOnFailure requirement (was tests: []) - dema-consulting-test-results.yaml: correct 3 test names to match actual tests (RecordTestOutcomes, SerializeToTrx, SerializeToJUnit) - cpp-generator.yaml: remove deleted CppEmitter_SanitizeFileName_OperatorName_ ReplacesInvalidChars from GroupOperatorOverloadsOnSinglePage - cpp-emitter.yaml: add direct tests to ApiMarkCpp-CppEmitter parent requirement; remove deleted CppEmitter_SanitizeFileName_OperatorName_ReplacesInvalidChars from WriteCombinedMemberPage Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…r bound - InMemoryMarkdownWriterFactory.cs: update 'name' param doc from 'null or empty' to 'null, empty, or whitespace' to match actual validation behavior - IMarkdownWriterTests.cs: expand cleanup catch from IOException to also cover UnauthorizedAccessException to avoid flaky test failures on Windows - FileMarkdownWriter.cs: document and enforce WriteHeading level upper bound of 6 (CommonMark ATX headings are only defined for H1-H6); update XML doc and add ArgumentOutOfRangeException.ThrowIfGreaterThan(level, 6) 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.
This pull request introduces several infrastructure and documentation improvements to the project, focusing on review configuration, spelling, markdown linting, and documentation for new output formats. The most significant changes are the expansion and clarification of the reviewmark review definitions, the addition of a
.gitattributesfile for consistent line endings, and updates to the documentation and spell checker configuration.Review and Documentation Configuration:
.reviewmark.yamlto add fine-grained review definitions for new components (such asIApiEmitter,EmitConfig, and various DotNet/Cpp emitters and models), clarify review titles, and update paths for more targeted code and documentation reviews. This includes splitting generator reviews into more granular units and adding new artifacts for OTS and third-party components. [1] [2] [3] [4]docs/design/api-mark-core.mdto describe the new two-stage pipeline (IApiGenerator.ParsereturningIApiEmitter, which then emits documentation withEmitConfig), and to document the new output format options and their configuration. [1] [2] [3]Infrastructure and Tooling:
.gitattributesfile to enforce consistent LF line endings for all text files and CRLF for Windows batch files, improving cross-platform consistency and reviewmark fingerprinting..markdownlint-cli2.yamlto ignore additional build and fixture output directories, reducing false positives in markdown linting..cspell.yamlwith new technical and domain-specific terms to improve spell checking accuracy for the codebase. [1] [2] [3] [4]User-Facing Documentation:
README.mdto document support for multiple output formats (--format single-file) and example code block rendering, along with new CLI usage examples for generating single-file API references for both .NET and C++. [1] [2]