Generated doc comments: payload wording on no-content envelopes and adapters #177

Activity

1. Blind-Striker

   added this to the 1.0 milestone on Oct 14, 2026
2. Blind-Striker

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Oct 14, 2026
3. Blind-Striker

   added this to opencode-sdk-dotneton Oct 14, 2026
4. Blind-Striker

   moved this to Queue in opencode-sdk-dotneton Oct 14, 2026
5. Blind-Striker commented on Oct 14, 2026

   

   Blind-Striker

   on Oct 14, 2026

   CollaboratorAuthor

   More actions

   Root causes, located on master a5def42d (a read-only scan, about 78 matches across about 70 generated files):

   • The article is hard-coded. The fallback doc comments build "a {name}" whatever the name's first sound is:
     • tools/OpenCode.Sdk.Tools/Generator/Emission/ModelEmitter.cs:64: Represents a {GeneratedDisplayName.Of(model.Name)} value.
     • HoistedInterfaceEmitter.cs:30: Represents a {plan.Name} value., which is also not passed through GeneratedDisplayName.
     • StructuralUnionEmitter.cs:77: Represents a {DisplayName(union.Name)} structural union.
     • StructuralUnionEmitter.cs:197: Creates a {DisplayName(union.Name)} from its {DisplayName(arm.Name)} arm.
     • UnionEmitter.cs:62: Represents a {GeneratedDisplayName.Of(union.ConceptName)} union.
   • Acronyms and versions split. GeneratedDisplayName.cs:11 joins CSharpNamePolicy.SplitWords(name) lowercased, so V1 reads as v 1, and acronyms lose their casing.

   A fix picks the article in one place (from the display name's first sound, with an exception list for acronyms) and keeps known tokens such as V1 and the brand acronyms whole. Generated output then changes only through generate, after the layout's first slice (#173) moves the emitters.
6. Blind-Striker

   added a parent issue on Oct 18, 2026

   • Consumer documentation: the developer-experience findings #504
7. Blind-Striker commented on Oct 23, 2026

   

   Blind-Striker

   on Oct 23, 2026

   Last edited by Blind-Striker

   CollaboratorAuthor

   More actions

   Re-scoped to item 3 only. Items 1 and 2 are fixed on master (46b65a7e) by #418 (fe05ebff, "generated summaries are grammatical and spell brands right"):

   • Article: AgentInfo reads "Represents an agent info value." and ExperimentalMigrationV1Status reads "Represents an experimental migration V1 status structural union." No generated /// line in src/OpenCode.Sdk puts "a" before a vowel sound; the one "a" + vowel left is a curated "as a Unix timestamp" (ModelInfoTime.cs:12).
   • Acronyms and versions: CredentialOAuth reads "Represents a credential OAuth value." No generated summary splits a version into "v 1".
   • One helper: every emitter that builds a display name calls GeneratedDisplayName (Model, Union, StructuralUnion, HoistedInterface, ExtensibleEnum). StructuralUnionEmitter no longer has its own copy.

   Item 3 is still open. The payload wording is emitted unconditionally:

   • tools/OpenCode.Sdk.Tools/Generator/Emission/EnvelopeEmitter.cs:188: "Initializes an error-path instance; the payload stays unset behind its guard." It appears in all 139 envelopes, including no-content ones such as CredentialActivateResponse (src/OpenCode.Sdk/Credentials/CredentialActivateResponse.cs:20).
   • tools/OpenCode.Sdk.Tools/Generator/Emission/ResponseAdapterEmitter.cs:155: "Maps the declared UTF-8 success body onto the typed envelope." It also appears on no-content adapters such as CredentialActivateResponseAdapter.

   Both emitters belong to the per-operation behaviour epic (#482), which already owns their shared code, so this issue moves under #482.
8. Blind-Striker

   changed the title [-]Generated doc comments: wrong article, split acronyms, and payload text on no-content responses[/-] [+]Generated doc comments: payload wording on no-content envelopes and adapters[/+] on Oct 23, 2026
9. Blind-Striker

   removed a parent issue on Oct 23, 2026

   • Consumer documentation: the developer-experience findings #504
10. Blind-Striker

    added a parent issue on Oct 23, 2026

    • [GEN-E5] Fixed per-operation behaviour moves into hand-written bases #482
11. Blind-Striker

    added a commit that references this issue on Oct 26, 2026

    fix(generator): no-content envelopes and adapters stop mentioning a p…

    ...

    This issue will close once commit 1412cd4 is merged into the 'master' branch.

    1412cd4
12. Blind-Striker

    closed this as completedin #648on Oct 26, 2026