[Automated][azure-resource-manager] Fix doc comment typos and add suppress documentation for ARM library (#4433)

- Fix 'resource being patched' → 'resource being listed' in list
operation templates (ArmListBySubscription, ArmResourceListByParent,
ArmResourceListAtScope)
- Fix 'createOrUpdate operation' → 'createOrReplace operation' in
ArmResourceCreateOrReplaceSync and Extension.CreateOrReplaceSync doc
comments
- Fix 'Extension>ManagementGroup' → 'Extension.ManagementGroup' typo
- Fix malformed @doc interpolation '{name PrivateEndpointConnection}' →
'{name} PrivateEndpointConnection' in private-endpoints.tsp
- Fix 'resource being created or updated' → 'resource being updated' in
legacy CustomPatchAsync (PATCH only updates, never creates)
- Document #suppress requirement for ArmTagsPatch*/ArmResourcePatch* in
resource-operations.md
- Regenerate reference docs (interfaces.md)
- Update knowledge base with lessons learned

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Chenjie Shi <tadelesh.shi@live.cn>

Author: 4 people

.chronus/changes/fix-arm-doc-comments-typos-2026-5-18-10-43-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Fix doc comment typos in ARM library: list operations incorrectly said "patched", CreateOrReplace operations said "createOrUpdate", extension operations had `>` instead of `.`, and @doc tag had malformed string interpolation.

eng/scripts/doc-updater/knowledge/azure-resource-manager.md

@@ -68,15 +68,35 @@ Old paths like `dynatrace/`, `tenantResource/`, `arm-scenarios/singleton/`, `ope
 - The `@defaultResourceKeySegmentName` decorator on `ResourceNameParameter` auto-generates key and segment names.
 - Ghost `@template` or `@param` tags in doc comments (referencing non-existent parameters) should be removed.
 - The `nsp-operations.tsp` file has Action/ActionAsync templates that are POST operations, not GET — doc comments must reflect this.
+- List operations (`ArmListBySubscription`, `ArmResourceListByParent`, `ArmResourceListAtScope`) must say "the resource being listed" — NOT "being patched" (copy-paste error from patch templates).
+- `CreateOrReplace*` operations should say "createOrReplace" in their @template Response description. The deprecated `CreateOrUpdate*` ops say "createOrUpdate" (correct for them). In `legacy-types/`, operations named `CreateOrReplace*` still use "createOrUpdate" because the `@armResourceCreateOrUpdate` decorator confirms the ARM-level semantics.
+- In `lib/extension/operations.tsp`, template doc comments use `Extension.Subscription`, `Extension.ManagementGroup`, `Extension.ResourceGroup` (dot-separated, not `>`).
 
 ## Build Requirements
 
-- Node.js >= 22 is required for `pnpm install`.
+- Node.js >= 22 is required for `pnpm install` and `pnpm build`.
 - Build the ARM package with: `pnpm -r --filter "@azure-tools/typespec-azure-resource-manager..." build`
 - Format with: `pnpm format`
+- If the default Node.js is too old, download Node 22 manually and prepend to PATH.
 
 ## Operation Templates (Not Deprecated)
 
 `ArmResourcePatchAsync` and `ArmResourcePatchSync` exist and are not deprecated, though they are noted as "not recommended" in resource-operations.md. `ArmCustomPatchSync` and `ArmCustomPatchAsync` are the preferred alternatives.
 
 `TrackedResourceOperations` interface is current. `ResourceOperations` is deprecated (use `TrackedResourceOperations` instead).
+
+## ArmTagsPatch Suppress Requirement
+
+`ArmTagsPatchSync`, `ArmTagsPatchAsync`, `ArmResourcePatchSync`, and `ArmResourcePatchAsync` use `@patch(#{ implicitOptionality: true })` which triggers a deprecation warning. Users must add `#suppress "@typespec/http/deprecated-implicit-optionality" "Legacy"` at the usage site. This is documented in `resource-operations.md`.
+
+## Getting-Started Guide Style
+
+The `@service` decorator should NOT include a `version` parameter (version comes from `@versioned` when used). The guide uses `ArmCustomPatchSync` (not ArmTagsPatch) because that is the recommendation, based on the requirements of the ARM RPC (Resource Provider Contract).
+
+## Feedback Corrections Applied
+
+- `step03.md`: Use `...ResourceNameParameter<AddressResource, KeyName = "addressName", SegmentName = "addresses">` instead of manual `@key/@segment name` fields for child resources.
+- `step04.md`: Use individual operation declarations (not `TrackedResourceOperations<User, UserProperties>`) in the interface example, with `ArmCustomPatchSync` for the update operation.
+- `step05.md`: Remove `version` from `@service` decorator; use `...ResourceNameParameter<User>` instead of manual key/segment/path.
+- `deprecation.tsp`: The ExtensionResourceBase deprecation message must say "Foundations.ExtensionResource" (not "ProxyResource").
+- `arm-legacy-operations-discourage` rule was removed from linter registration; its rule doc file and linter.md entry should not exist.

eng/scripts/doc-updater/knowledge/azure-resource-manager.meta.json

@@ -1,6 +1,6 @@
 {
-  "lastCommit": "c28b4645003e1b948275b7c2854911dd09d800c8",
-  "lastUpdated": "2026-04-29T04:58:33.314Z",
+  "lastCommit": "1eb05cd5d698c92f92a0c468276e87b26bc6a718",
+  "lastUpdated": "2026-05-18T11:02:47.905Z",
   "analyzedPaths": [
     "packages/typespec-azure-resource-manager/src",
     "packages/typespec-azure-resource-manager/lib",

packages/typespec-azure-resource-manager/lib/extension/operations.tsp

@@ -9,7 +9,7 @@ using Azure.ResourceManager.Private;
 
 /**
  * List an extension resource at the given target scope
- * @template TargetResource The target to list at, e.g. Extension.Subscription or Extension>ManagementGroup or Extension.ResourceGroup
+ * @template TargetResource The target to list at, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource the resource being listed
  * @template Parameters Optional. Additional parameters after the path parameters
  * @template Response Optional. The success response for the list operation
@@ -144,7 +144,7 @@ op CreateOrUpdateAsync<
  * @template TargetResource the target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource the resource being created or replaced
  * @template Parameters Optional. Additional parameters after the path parameters
- * @template Response Optional. The success response for the createOrUpdate operation
+ * @template Response Optional. The success response for the createOrReplace operation
  * @template Error Optional. The error response, if non-standard.
  * @template OverrideResourceName Optional. Allows overriding the resource name for this scope in generated clients.
  */

packages/typespec-azure-resource-manager/lib/legacy-types/operations.tsp

@@ -121,7 +121,7 @@ interface RoutedOperations<
 
   /**
    * A long-running resource Update (PATCH)
-   * @template Resource the resource being created or updated
+   * @template Resource the resource being updated
    * @template PatchModel the PATCH request model
    * @template LroHeaders Optional.  Allows overriding the lro headers returned on resource create
    * @template Parameters Optional. Additional parameters after the path parameters

packages/typespec-azure-resource-manager/lib/operations.tsp

@@ -9,7 +9,7 @@ namespace Azure.ResourceManager;
 
 /**
  * A resource list operation, at the subscription scope
- * @template Resource the resource being patched
+ * @template Resource the resource being listed
  * @template Parameters Optional. Additional parameters after the path parameters
  * @template Response Optional. The success response for the list operation
  * @template Error Optional. The error response, if non-standard.
@@ -58,7 +58,7 @@ op ArmListBySubscriptionScope<
 
 /**
  * A resource list operation, at the scope of the resource's parent
- * @template Resource the resource being patched
+ * @template Resource the resource being listed
  * @template BaseParameters Optional. Allows overriding the operation parameters
  * @template ParentName Optional. The name of the parent resource
  * @template ParentFriendlyName Optional. The friendly name of the parent resource
@@ -92,7 +92,7 @@ op ArmResourceListByParent<
 
 /**
  * A resource list operation, with scope determined by BaseParameters
- * @template Resource the resource being patched
+ * @template Resource the resource being listed
  * @template BaseParameters Optional. Allows overriding the operation parameters
  * @template Parameters Optional. Additional parameters after the path parameters
  * @template Response Optional. The success response for the list operation
@@ -276,7 +276,7 @@ op ArmResourceCreateOrUpdateSync<
  * @template Resource the resource being created or replaced
  * @template BaseParameters Optional. Allows overriding the operation parameters
  * @template Parameters Optional. Additional parameters after the path parameters
- * @template Response Optional. The success response for the createOrUpdate operation
+ * @template Response Optional. The success response for the createOrReplace operation
  * @template Error Optional. The error response, if non-standard.
  * @template Provider Optional. The provider namespace model for the resource.
  */

packages/typespec-azure-resource-manager/lib/private-endpoints.tsp

@@ -283,7 +283,7 @@ interface PrivateEndpoints<
    * @template OverrideResourceName Optional. The name of the private endpoint connection resource being operated on.
    */
   @autoRoute
-  @doc("Update a {name PrivateEndpointConnection}", ParentResource)
+  @doc("Update a {name} PrivateEndpointConnection", ParentResource)
   @builtInResourceOperation(ParentResource, Resource, "update", OverrideResourceName)
   @Private.enforceConstraint(ParentResource, Foundations.Resource)
   @patch(#{ implicitOptionality: false })

website/src/content/docs/docs/howtos/ARM/resource-operations.md

@@ -147,6 +147,14 @@ resource type and your custom PATCH request type as parameters, giving you full
 PATCH schema. The `ArmTagsPatch*` templates take the resource type as a parameter and only allow
 updating ARM tags.
 
+> **Note:** The `ArmTagsPatch*` and `ArmResourcePatch*` templates use implicit optionality, which
+> requires a suppression at the usage site:
+>
+> ```tsp
+> #suppress "@typespec/http/deprecated-implicit-optionality" "Legacy"
+> update is ArmTagsPatchSync<ResourceType>;
+> ```
+
 > **Note:** The `ArmResourcePatch*` templates are **not recommended**. They rely on Lifecycle.Update
 > visibility analysis to automatically determine which properties are included in the PATCH schema,
 > but this analysis is only performed by the typespec-autorest emitter and will not be replicated in

website/src/content/docs/docs/libraries/azure-resource-manager/reference/interfaces.md

@@ -984,7 +984,7 @@ op Azure.ResourceManager.ArmListBySubscription(apiVersion: string, subscriptionI
 
 | Name       | Description                                               |
 | ---------- | --------------------------------------------------------- |
-| Resource   | the resource being patched                                |
+| Resource   | the resource being listed                                 |
 | Parameters | Optional. Additional parameters after the path parameters |
 | Response   | Optional. The success response for the list operation     |
 | Error      | Optional. The error response, if non-standard.            |
@@ -1209,14 +1209,14 @@ op Azure.ResourceManager.ArmResourceCreateOrReplaceSync(resource: Resource): Res
 
 #### Template Parameters
 
-| Name           | Description                                                     |
-| -------------- | --------------------------------------------------------------- |
-| Resource       | the resource being created or replaced                          |
-| BaseParameters | Optional. Allows overriding the operation parameters            |
-| Parameters     | Optional. Additional parameters after the path parameters       |
-| Response       | Optional. The success response for the createOrUpdate operation |
-| Error          | Optional. The error response, if non-standard.                  |
-| Provider       | Optional. The provider namespace model for the resource.        |
+| Name           | Description                                                      |
+| -------------- | ---------------------------------------------------------------- |
+| Resource       | the resource being created or replaced                           |
+| BaseParameters | Optional. Allows overriding the operation parameters             |
+| Parameters     | Optional. Additional parameters after the path parameters        |
+| Response       | Optional. The success response for the createOrReplace operation |
+| Error          | Optional. The error response, if non-standard.                   |
+| Provider       | Optional. The provider namespace model for the resource.         |
 
 ### `ArmResourceCreateOrUpdateAsync` {#Azure.ResourceManager.ArmResourceCreateOrUpdateAsync}
 
@@ -1349,7 +1349,7 @@ op Azure.ResourceManager.ArmResourceListAtScope(): Response | Error
 
 | Name           | Description                                               |
 | -------------- | --------------------------------------------------------- |
-| Resource       | the resource being patched                                |
+| Resource       | the resource being listed                                 |
 | BaseParameters | Optional. Allows overriding the operation parameters      |
 | Parameters     | Optional. Additional parameters after the path parameters |
 | Response       | Optional. The success response for the list operation     |
@@ -1368,7 +1368,7 @@ op Azure.ResourceManager.ArmResourceListByParent(): Response | Error
 
 | Name               | Description                                               |
 | ------------------ | --------------------------------------------------------- |
-| Resource           | the resource being patched                                |
+| Resource           | the resource being listed                                 |
 | BaseParameters     | Optional. Allows overriding the operation parameters      |
 | ParentName         | Optional. The name of the parent resource                 |
 | ParentFriendlyName | Optional. The friendly name of the parent resource        |
@@ -1797,7 +1797,7 @@ op Azure.ResourceManager.Extension.CreateOrReplaceSync(apiVersion: string, subsc
 | TargetResource       | the target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup |
 | ExtensionResource    | the resource being created or replaced                                                                   |
 | Parameters           | Optional. Additional parameters after the path parameters                                                |
-| Response             | Optional. The success response for the createOrUpdate operation                                          |
+| Response             | Optional. The success response for the createOrReplace operation                                         |
 | Error                | Optional. The error response, if non-standard.                                                           |
 | OverrideResourceName | Optional. Allows overriding the resource name for this scope in generated clients.                       |
 
@@ -1950,7 +1950,7 @@ op Azure.ResourceManager.Extension.ListByTarget(apiVersion: string, subscription
 
 | Name                 | Description                                                                                                |
 | -------------------- | ---------------------------------------------------------------------------------------------------------- |
-| TargetResource       | The target to list at, e.g. Extension.Subscription or Extension>ManagementGroup or Extension.ResourceGroup |
+| TargetResource       | The target to list at, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup |
 | ExtensionResource    | the resource being listed                                                                                  |
 | Parameters           | Optional. Additional parameters after the path parameters                                                  |
 | Response             | Optional. The success response for the list operation                                                      |
@@ -2514,7 +2514,7 @@ op Azure.ResourceManager.Legacy.RoutedOperations<ParentParameters, ResourceTypeP
 
 | Name                 | Description                                                             |
 | -------------------- | ----------------------------------------------------------------------- |
-| Resource             | the resource being created or updated                                   |
+| Resource             | the resource being updated                                              |
 | PatchModel           | the PATCH request model                                                 |
 | LroHeaders           | Optional. Allows overriding the lro headers returned on resource create |
 | Parameters           | Optional. Additional parameters after the path parameters               |