From f54ced321c9d2377b520f89b20df7a6e28b4317c Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 11:02:18 +0000 Subject: [PATCH] docs(tcgc): update knowledge base with feedback lessons and source insights MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add lessons from PR #4430 feedback (exact-name spec patterns) - Document orphan type ordering (models→enums→unions) for stable naming - Document example matching autorest scope design decision - Document BinarySerializationOptions.filename type correction - Update metadata to track latest analyzed commit Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- eng/scripts/doc-updater/knowledge/tcgc.md | 16 ++++++++++++++++ eng/scripts/doc-updater/knowledge/tcgc.meta.json | 4 ++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/eng/scripts/doc-updater/knowledge/tcgc.md b/eng/scripts/doc-updater/knowledge/tcgc.md index cc10c74da2..ff843ebc58 100644 --- a/eng/scripts/doc-updater/knowledge/tcgc.md +++ b/eng/scripts/doc-updater/knowledge/tcgc.md @@ -170,6 +170,15 @@ namespace (@clientNamespace), naming (@clientName), overload, structure (@client - Multiple request content types: enum with one value per content type. - Multiple response content types: single constant with comma-joined string (structured types first). - Constants and enums get proper generated names via the naming context path (e.g., `DownloadFileMultipleContentTypesAccept`). +- For file bodies with multiple content types, TCGC reuses the File model's `contentType` property's union type so that the synthesized `contentType` header parameter and the File model's property reference the same `SdkEnumType` instance. + +## Example Matching (June 2026) + +- Example file operation IDs are resolved under the `autorest` scope (not the per-language scope) to avoid per-language `@clientLocation`/`@clientName` overrides breaking example linkage. This ensures the same example file matches regardless of which language emitter is consuming TCGC. + +## BinarySerializationOptions (June 2026) + +- The `filename` property on `BinarySerializationOptions` is of type `SdkModelPropertyType` (not the raw TypeSpec `ModelProperty`). This was corrected from the original implementation to use TCGC's own type system consistently. ## Usage Flag Propagation @@ -205,3 +214,10 @@ namespace (@clientNamespace), naming (@clientName), overload, structure (@client - `listOrphanTypes` no longer iterates only user-defined namespaces. It now uses `listScopedDecoratorData` to find all types and namespaces with an explicit `@usage` decorator, including types in imported libraries (e.g., `@@usage(Azure.Core.Foundations.Error, Usage.input)`). - When `@usage` is applied to a namespace, the function recursively descends into sub-namespaces to collect all models, enums, and unions. - Types with `@hierarchyBuilding` are also collected separately (only when legacy hierarchy building is enabled). +- **Ordering**: `listOrphanTypes` returns types in a stable order: models first, then enums, then unions. This ensures anonymous types (e.g., anonymous model variants inside unions) get their generated name from the model property context rather than the union context, producing stable names like `OuterWithNullableValue` instead of `RecursiveNullableType1`. + +## Feedback Lessons (PR #4430) + +- Only ONE `#suppress "experimental-feature" "exact"` directive is needed per property — it covers all subsequent `@clientName(exact(...))` decorators on that property. +- When creating exact-name Spector specs, the namespace needs `@clientNamespace` for BOTH Java (`"azure.clientgenerator.core.exactname"`) AND Python (`"specs.azure.clientgenerator.core.exactname"`) so tests pass in both language emitter test suites. +- The @clientNamespace for python should be formatted multi-line if it exceeds a reasonable line length. diff --git a/eng/scripts/doc-updater/knowledge/tcgc.meta.json b/eng/scripts/doc-updater/knowledge/tcgc.meta.json index 77978222dd..65f5461dcf 100644 --- a/eng/scripts/doc-updater/knowledge/tcgc.meta.json +++ b/eng/scripts/doc-updater/knowledge/tcgc.meta.json @@ -1,6 +1,6 @@ { - "lastCommit": "b166149c75cfcf8b63e8205fad4bee05a98aef1a", - "lastUpdated": "2026-05-25T10:51:38.701Z", + "lastCommit": "a04ee76e9f6f1d7918955269c7a54af2c0e9c685", + "lastUpdated": "2026-06-08T10:59:23.790Z", "analyzedPaths": [ "packages/typespec-client-generator-core/src", "packages/typespec-client-generator-core/lib",