fix(http-client-csharp): use current operation docs for compatibility overloads

[JoshLove-msft]

Fixes #11994

Summary

The shared C# generator now builds documentation for added-optional-parameter, nullable-value-type, and reduced-arity compatibility overloads from the current method, rather than documentation reconstructed from the released contract.

• Preserve structured summaries, current operation metadata, cref tags, returns, and custom exception reasons.
• Map parameter documentation and exception references to the shim's preserved signature, excluding omitted parameters and documenting the shim's existing validation/null guards.
• Leave primary method documentation and parameter providers unchanged. Missing or empty current documentation never falls back to stale released prose.
• Preserve existing signatures, parameter/default compatibility policy, forwarding bodies, and exception behavior. No Compute-generated code, SDK dependencies, or changelog changes.

Released contract DLL/XML inputs are selected by ApiCompatVersion. This repairs stale metadata and indentation across release/baseline round trips; it does not assume that repeated generation against an unchanged baseline adds whitespace.

Regression coverage

22 new regression cases cover sync/async optional-parameter shims; legacy continuation indentation; current structured metadata and cref/return content; parameter-name normalization, reserved names, parameter filtering and exception reasons; unchanged primary docs; nullable/reduced-arity shims; absent/empty/inherited documentation; and preservation through parameter reordering and client suppression processing.

The baseline regression compiles DLL and XML documentation, reloads that released contract through Roslyn metadata, and repeats across successive baselines. Rendered shim docs remain identical and current, and compilation checks reject invalid parameter documentation references.

Validation

Check	Result
npm run build	Passed; generator build has 0 warnings/errors
Full shared generator unit suite	2,293 passed
Full ClientModel generator unit suite	1,727 passed
Input generator unit suite	178 passed
npm run test:emitter	244 passed, 2 existing skips
eng/scripts/Generate.ps1	Passed (14m02s); no generated-library diff
Root pnpm format and package npm run format	Passed
dotnet format whitespace --verify-no-changes on changed C# files	Passed
npm run cop	cop checks passed.
Repository-standard oxlint on the emitter	Passed

Environment notes: full generator suites used a temporary short drive mapping to this same worktree to avoid existing Windows long-path/mixed-separator test-data failures; the mapping was removed afterward. Repository-pinned pnpm 11.10 was invoked locally without replacing global pnpm, and command-local NODE_OPTIONS=--experimental-strip-types enabled the installed Node 22.14 to load the repository's TypeScript tooling. npm run lint still refers to unavailable ESLint despite the repository's move to oxlint; the current repository oxlint check was run instead. No dependency manifests, lockfiles, global tools, or CI configuration were changed.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-csharp@11995

commit: 497e54c

[github-actions]

No changes needing a change description found.

[Copilot]

🟢 Approval recommended

No unresolved issues remain, and comprehensive regression coverage is included.

Pull request overview

Updates C# compatibility overloads to use current operation XML documentation while preserving legacy signatures and forwarding behavior.

Changes:

• Reworked shim documentation and exception mapping.
• Added published-baseline regression coverage.
• Documented the updated compatibility behavior.

File summaries

File	Description
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Utilities/TestData/BackCompatHelperTests/CompatibilityDocumentationIsStableAcrossPublishedBaselines/OperationClient.cs	Provides stale published-documentation baseline fixtures.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Utilities/BackCompatHelperTests.cs	Adds compatibility documentation regression tests.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/BackCompatHelper.cs	Builds filtered shim documentation from current methods.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Statements/XmlDocParamStatement.cs	Preserves parameter documentation content.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Statements/XmlDocExceptionStatement.cs	Preserves exception reasons and remaps parameter references.
packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator.ClientModel/test/Providers/ClientProviders/ClientProviderTests.cs	Verifies behavior through client processing.
packages/http-client-csharp/generator/docs/backward-compatibility.md	Documents the updated compatibility behavior.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

• Files reviewed: 6/6 changed files
• Comments generated: 1
• Review effort level: Lite