Fix #917 and #918: doc-comment emission defects found reviewing #916 - #920
Merged
Conversation
…nel change The 5.3.0 release regenerated the ExampleRecipes Generated folders with the parameterised-channel breaking change from #914, but left recipes 037, 038, and 039 calling the removed parameterless StartAsync() overload, so ExampleRecipes.slnx did not build. The call sites now supply the channel parameter, the simulated broker publishes target the concrete channel the consumer subscribes to, and the README samples match the code again. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0157Tdszg6wzgWeKgGYRBNKV
…omments with signatures A response links entry's description was the last place specification text reached a generated doc comment verbatim; a line break in it terminated the comment and the remainder parsed as source code, the failure mode #916 reported for operation summaries. The 3.0, 3.1, and 3.2 client generators now route it through CodeEmitHelpers.EscapeXml (#917). Generated doc comments also contradicted the signatures they document, so a consuming project with GenerateDocumentationFile and TreatWarningsAsErrors failed its build on CS1572/CS1573. The model templates' constructor, conversion-operator, From<T>, and TryParseValue param tags now match, and the OpenAPI client method docs cover the trailing validationMode and responseValidationMode parameters in all four generators (#918). Covspec link tests pin the flattened, escaped emission; a new GeneratedDocumentationTests suite runs the CLI and compiles its output under DocumentationMode.Diagnose, gating errors and the doc-mismatch warning family. All new tests failed against the unfixed generators with exactly the defect diagnostics before passing with the fixes. Example recipes are regenerated; the diff is doc-comment lines and lock metadata. CS1591 is tracked separately in #919. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0157Tdszg6wzgWeKgGYRBNKV
…s for 5.3.0 The model templates changed in the #918 fix, so every C/ directory is regenerated; B/ is untouched. Modified-file diffs are doc-comment lines only. The sweep also carries 5.3.0-era nested type-name truncation renames on the large schemas (Ui5, Krakend, GeoJson, CmakePresets, and friends), because 5.3.0 changed the truncation without regenerating C/; git pairs those as delete plus add. Corvus.Text.Json.AsyncApi.Benchmarks was already broken on main: its hand-written BenchmarkTransport still implemented the pre-5.3.0 RequestAsync signature without the JsonWorkspace parameter, and its checked-in Generated folder predated 5.3.0. The transport gains the workspace parameter (unused by design; the reply is pre-parsed at setup), the Generated folder is regenerated with the current asyncapi-generate, and the harness follows the models into the .Models subnamespace. The benchmarks solution builds with no warnings. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0157Tdszg6wzgWeKgGYRBNKV
The V4 engine was inspected for the same defect classes and verified clean: its doc param tags name parameters that exist in the V4 signatures, and its AppendParagraphs emits description text per line, HTML-encoded, so a multi-line or markup-carrying description cannot escape the doc comment. GeneratedDocumentationTests now runs the same five fixture schemas through --engine V4 and compiles the output under DocumentationMode.Diagnose, so both engines stay guarded rather than only the one that was broken. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0157Tdszg6wzgWeKgGYRBNKV
Contributor
Code Coverage Summary Report - Windows (net10.0)Summary
CoverageCorvus.Json.CodeGeneration - 80.5%
Corvus.Json.CodeGeneration.CSharp - 81.8%
Corvus.Json.ExtendedTypes - 74.9%
Corvus.Json.JsonReference - 76.7%
Corvus.Text.Json - 93.9%
Corvus.Text.Json.AsyncApi - 62%
Corvus.Text.Json.AsyncApi.Amqp - 0.3%
Corvus.Text.Json.AsyncApi.AzureServiceBus - 0%
Corvus.Text.Json.AsyncApi.CodeGeneration - 93.3%
Corvus.Text.Json.AsyncApi.Kafka - 0.3%
Corvus.Text.Json.AsyncApi.Mqtt - 0.5%
Corvus.Text.Json.AsyncApi.Nats - 0.3%
Corvus.Text.Json.AsyncApi.Polly - 100%
Corvus.Text.Json.AsyncApi.Testing - 96%
Corvus.Text.Json.AsyncApi.WebSocket - 0%
Corvus.Text.Json.CodeGeneration - 93.2%
Corvus.Text.Json.JMESPath - 93.8%
Corvus.Text.Json.JMESPath.CodeGeneration - 97.7%
Corvus.Text.Json.Jsonata - 91.6%
Corvus.Text.Json.Jsonata.CodeGeneration - 88.5%
Corvus.Text.Json.JsonLogic - 95.1%
Corvus.Text.Json.JsonLogic.CodeGeneration - 92.8%
Corvus.Text.Json.JsonPath - 94.7%
Corvus.Text.Json.JsonPath.CodeGeneration - 96.1%
|
Contributor
Contributor
Code Coverage Summary Report - Linux (net10.0)Summary
CoverageCorvus.Json.CodeGeneration - 80.5%
Corvus.Json.CodeGeneration.CSharp - 81.8%
Corvus.Json.ExtendedTypes - 74.9%
Corvus.Json.JsonReference - 76.7%
Corvus.Text.Json - 94.1%
Corvus.Text.Json.AsyncApi - 62%
Corvus.Text.Json.AsyncApi.Amqp - 0.3%
Corvus.Text.Json.AsyncApi.AzureServiceBus - 0%
Corvus.Text.Json.AsyncApi.CodeGeneration - 93.3%
Corvus.Text.Json.AsyncApi.Kafka - 0.3%
Corvus.Text.Json.AsyncApi.Mqtt - 0.5%
Corvus.Text.Json.AsyncApi.Nats - 0.3%
Corvus.Text.Json.AsyncApi.Polly - 100%
Corvus.Text.Json.AsyncApi.Testing - 96%
Corvus.Text.Json.AsyncApi.WebSocket - 0%
Corvus.Text.Json.CodeGeneration - 93.2%
Corvus.Text.Json.JMESPath - 93.8%
Corvus.Text.Json.JMESPath.CodeGeneration - 97.7%
Corvus.Text.Json.Jsonata - 91.6%
Corvus.Text.Json.Jsonata.CodeGeneration - 88.5%
Corvus.Text.Json.JsonLogic - 95.1%
Corvus.Text.Json.JsonLogic.CodeGeneration - 92.8%
Corvus.Text.Json.JsonPath - 94.7%
Corvus.Text.Json.JsonPath.CodeGeneration - 96.1%
Corvus.Text.Json.OpenApi - 86.7%
|
Contributor
Code Coverage Summary Report - Windows (net481)Summary
CoverageCorvus.Json.CodeGeneration - 80.6%
Corvus.Json.CodeGeneration.CSharp - 81.5%
Corvus.Json.ExtendedTypes - 72.6%
Corvus.Json.JsonReference - 73.8%
Corvus.Text.Json - 92.7%
Corvus.Text.Json.CodeGeneration - 86.2%
Corvus.Text.Json.JMESPath - 93.8%
Corvus.Text.Json.JMESPath.CodeGeneration - 97.7%
Corvus.Text.Json.Jsonata - 91.8%
Corvus.Text.Json.Jsonata.CodeGeneration - 88.6%
Corvus.Text.Json.JsonLogic - 95.1%
Corvus.Text.Json.JsonLogic.CodeGeneration - 92.8%
Corvus.Text.Json.JsonPath - 95%
Corvus.Text.Json.JsonPath.CodeGeneration - 96.1%
Corvus.Text.Json.Patch - 97.5%
Corvus.Text.Json.Toon - 88.2%
Corvus.Text.Json.Validator - 92.4%
Corvus.Text.Json.Yaml - 90.8%
Corvus.Toon.SystemTextJson - 90%
Corvus.Yaml.SystemTextJson - 88.7%
|
Contributor
|
This was referenced Aug 9, 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
1 participant
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.
Fixes #917 and #918, the two residual doc-comment emission defects found while reviewing #916.
What changed
#917: link descriptions escaped. The
descriptionof a responselinksentry was the last place specification text reached a generated///doc comment verbatim. A line break in it terminated the comment and the remainder parsed as source code, the same failure mode #916 reported for operation summaries. The 3.0, 3.1, and 3.2 client generators now route it throughCodeEmitHelpers.EscapeXml, as every other doc-comment site has since #915. OpenAPI 2.0 has no links concept.#918: generated doc comments match their signatures. Any consuming project with
GenerateDocumentationFileandTreatWarningsAsErrorsfailed its build on CS1572/CS1573 from generated code. Two layers were out of step:CodeGeneratorExtensions.cs): the(IJsonDocument parent, int idx)constructors were documented with a singlevaluetag; the conversion operators andFrom<T>documentedvaluewhile the parameter isinstance;TryParseValuedocumentedelementwhile emittingresult.From<T>also gains itstypeparamtag.validationMode/responseValidationModepair.Tests
CovSpec_ResponseLinks_MultiLineLinkDescription_*tests (3.0/3.1/3.2) pin the flattened, escaped single-line emission, driven by a multi-line,&-carrying link description added to the covspec fixtures.EscapeXmlitself gains flattening unit tests.GeneratedDocumentationTestsclass inCodeGenerator.Testsruns the real CLI (jsonschemaover five fixture schemas,openapi-clientover a new fixture with multi-line summary and link description) and compiles the output with Roslyn underDocumentationMode.Diagnose, gating both compile errors and the doc-mismatch warning family. This would also have caught Newline in OpenAPI summary copied into C# comment causing build failure #916 itself. CS1591 is deliberately not gated; that surface is Generated public members lack XML doc comments (CS1591 under GenerateDocumentationFile) #919.CS1519cascade from the raw link text), then passed with the fixes applied. The full OpenAPI codegen suite (1474 tests) is green.Regeneration and verification
docs/ExampleRecipesregenerated with the fixed generators; the diff is doc-comment lines plus lock-file metadata only. All nine runnable recipes exercised end-to-end (consumers verified to receive and dead-letter messages), and the three blocking server recipes start and listen.C/directories regenerated (model templates changed).B/untouched.Decisions and deferrals
main: the 5.3.0 release regenerated theirGenerated/folders with the parameterised-channel breaking change (Support parameterized AsyncAPI consumer channels #914) but left theirProgram.cscalling the removedStartAsync()overload, soExampleRecipes.slnxdid not build. This PR repairs the call sites (and the matching README samples), in its own commit.Corvus.Text.Json.AsyncApi.Benchmarkswas also already broken onmain: its hand-writtenBenchmarkTransportstill implemented the pre-5.3.0RequestAsyncsignature without theJsonWorkspaceparameter, and its checked-inGenerated/folder predated 5.3.0, so the benchmarks solution did not build. The transport signature is updated (the pre-parsed-reply design means the workspace is deliberately unused, and a remark says so), theGenerated/folder is regenerated with the currentasyncapi-generate, and the harness picks up the models' move to the.Modelssubnamespace.C/carries 5.3.0-era rename drift: 5.3.0 changed nested type-name truncation but did not regenerateC/, so this sweep pairs deletes/adds for deeply nested types on the large schemas alongside the doc-only edits. Modified-file diffs are doc-comment lines only. The sweep is its own commit.src/Corvus.Text.Json.AsyncApi26|30/Generatedleft as checked in: those folders are refreshed at release preparation (5.1 vintage today; Match on node containing string and pattern only ever calls string arm. #905 and OpenAPI and AsyncAPI generation for 5.3.0, with #913 and #914 #915 both left them), and a clean regen now would pull in every generator feature since 5.1, far beyond this fix. Their projects already suppress CS1572/CS1573, so they build unchanged; after the next release-prep regen those suppressions can narrow.valueparameters those tags name actually exist in the V4 signatures, and V4'sAppendParagraphsalready emits description text per line, HTML-encoded, so neither the Newline in OpenAPI summary copied into C# comment causing build failure #916/OpenAPI link description emitted verbatim into a C# doc comment breaks the generated build #917 failure mode nor the Generated code fails to build when the consuming project enables GenerateDocumentationFile (CS1572/CS1573) #918 mismatches apply. All five fixture schemas generated with--engine V4compile clean under documentation diagnostics, andGeneratedDocumentationTestsnow includes a V4-engine variant so both engines stay guarded.🤖 Generated with Claude Code
https://claude.ai/code/session_0157Tdszg6wzgWeKgGYRBNKV