[Automated][tcgc] Document `@override` path-param and `@clientLocation` type-conflict diagnostics

[github-actions]

Summary

Incremental TCGC documentation update covering source changes merged since the last doc update. Two new validation diagnostics needed user-facing guidance, so this PR adds concise :::caution admonitions to the client-library method howto and records lessons in the doc-updater knowledge base.

Documentation changes

website/src/content/docs/docs/howtos/Generate client libraries/04method.mdx:

• @clientLocation type conflict — added a caution noting that @clientLocation cannot move multiple parameters that share a name but have different types to the same client (common when applied to a templated parameter instantiated with different types across operations). Doing so emits a client-location-conflict warning and collapses the parameter to a single type. Fix: move the parameter per-operation instead. (Source: PR fix(tcgc): warn when @clientLocation moves same-named params with different types to a client #4716)
• @override path-parameter preservation — added a caution noting that the override operation must preserve every parameter realized as a @path parameter in the original HTTP route (keeping @path). Dropping or redeclaring such a parameter without @path reports an override-parameters-mismatch error, because the underlying route still requires the value; use @clientLocation to relocate instead. (Source: PRs [tcgc] fix path in override #4644 / fix(tcgc): avoid false positive override-parameters-mismatch for non-realized @path params #4684 / [tcgc] fix regression in override-parameters-mismatch #4693 / [TCGC] Fix @override check regression #4730)

Knowledge base

eng/scripts/doc-updater/knowledge/tcgc.md:

• Added Diagnostics entries for override-parameters-mismatch and client-location-conflict / parameterTypeConflict.
• Documented linter-rule doc conventions and the new csharp-no-url-suffix rule (PR Add no-url-suffix linter rule #4541), including the reusable codefix helpers in src/rules/codefix-helpers.ts.
• Recorded incremental doc-updater mechanics (source-only diffs; when admonitions vs. <ClientTabs> are appropriate).
• Captured the PR [Automated][tcgc] docs(tcgc): document per-service api-version for multi-service packages #4683 feedback lesson (use realistic date-based api-version identifiers, not placeholders like av1).

Notes

• The csharp-no-url-suffix rule page and linter reference row were already added by the rule's own source PR (Add no-url-suffix linter rule #4541) and are complete — verified, no change needed.
• The versioning-doc human fix from PR [Automated][tcgc] docs(tcgc): document per-service api-version for multi-service packages #4683 is already merged at HEAD — no change needed.
• No Spector coverage applies: these are validation/diagnostic-only and linter-rule changes, not positive wire-level scenarios, so they are documented as admonitions.
• chronus verify passes with no changeset required (docs-only change to a private package; .md changes are ignored by chronus config).
• Metadata (tcgc.meta.json) updated to record the checkout commit so the next incremental run starts from the right point.

Generated by Documentation Update Agent · 469.6 AIC · ⌖ 41.9 AIC · ⊞ 8K · ◷

---

Note

This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
The changes have been pushed to branch docs/tcgc-incremental-update-2026-07-06-0e310e7555535678.

Click here to create the pull request

To fix the permissions issue, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests. See also: gh-aw FAQ

Show patch preview (107 of 107 lines)

From 96cfe75f581c3fa7e25d6d5933c5a9430ce59c22 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 6 Jul 2026 11:12:49 +0000
Subject: [PATCH] docs(tcgc): document @override path-param and @clientLocation
 type-conflict diagnostics

Add two caution admonitions to the client-library method howto:
- @clientLocation cannot move multiple same-named params of different
  types to the same client (client-location-conflict warning).
- @override must preserve realized @path parameters; dropping or
  redeclaring them without @path triggers override-parameters-mismatch.

Update the doc-updater knowledge base with the new diagnostics, linter
rule documentation conventions (csharp-no-url-suffix), incremental
doc-updater mechanics, and the PR #4683 feedback lesson. Record the
checkout commit in the tcgc metadata.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 eng/scripts/doc-updater/knowledge/tcgc.md     | 25 +++++++++++++++++++
 .../doc-updater/knowledge/tcgc.meta.json      |  4 +--
 .../Generate client libraries/04method.mdx    |  8 ++++++
 3 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/eng/scripts/doc-updater/knowledge/tcgc.md b/eng/scripts/doc-updater/knowledge/tcgc.md
index 7b0d46fb..f2fcfb83 100644
--- a/eng/scripts/doc-updater/knowledge/tcgc.md
+++ b/eng/scripts/doc-updater/knowledge/tcgc.md
@@ -121,6 +121,8 @@ namespace (@clientNamespace), naming (@clientName), overload, structure (@client
 - `operation-not-in-client`: REMOVED in May 2026. This diagnostic no longer exists.
 - `inconsistent-multiple-service-dependency` (warning): Emitted when services merged into the same client depend on different versions of a shared library dependency. Documented in 03client.mdx under the "One Client from Multiple Services" section and in guideline.md under "Client Detection".
 - `legacy-hierarchy-building-conflict` (warning): Now only has `property-type-mismatch` message ID (the old `
... (truncated)