Improve documentation for ARM library decorators, interfaces, and models (#4494)

## Summary

Adds clear documentation to decorators, template interfaces, and models
in the ARM library that were missing docs or had unclear/incorrect
documentation.

### Changes

**lib/decorators.tsp**
- Fixed typo in @armLibraryNamespace
- Added descriptions to @armResourceAction, @armResourceCreateOrUpdate,
@armResourceRead, @armResourceUpdate, @armResourceDelete,
@armResourceList
- Expanded @armResourceCollectionAction description
- Fixed @armProviderNameValue wrong description
- Removed ghost @param tags from @armProviderNamespace and
@armVirtualResource
- Fixed @resourceBaseType param name to match implementation

**lib/interfaces.tsp**
- Fixed misleading doc on ResourceDeleteWithoutOkAsync

**lib/models.tsp**
- Improved docs for ResourceListCustomResult

**lib/legacy-types/**
- Fixed empty @doc

---------

Co-authored-by: tadelesh <chenjieshi@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.chronus/changes/fix-arm-lib-docs-improvement-2026-4-26-14-42-24.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Update documentation.

packages/samples/common-types/openapi/v3/types.json

@@ -221,6 +221,7 @@
     },
     "KeyVaultProperties": {
       "type": "object",
+      "description": "Properties of a KeyVault",
       "properties": {
         "keyIdentifier": {
           "type": "string",

packages/samples/common-types/openapi/v4/types.json

@@ -223,6 +223,7 @@
     },
     "KeyVaultProperties": {
       "type": "object",
+      "description": "Properties of a KeyVault",
       "properties": {
         "keyIdentifier": {
           "type": "string",

packages/samples/common-types/openapi/v5/types.json

@@ -223,6 +223,7 @@
     },
     "KeyVaultProperties": {
       "type": "object",
+      "description": "Properties of a KeyVault",
       "properties": {
         "keyIdentifier": {
           "type": "string",

packages/samples/common-types/openapi/v6/types.json

@@ -201,6 +201,7 @@
     },
     "KeyVaultProperties": {
       "type": "object",
+      "description": "Properties of a KeyVault",
       "properties": {
         "keyIdentifier": {
           "type": "string",

packages/typespec-azure-resource-manager/README.md

@@ -117,7 +117,9 @@ the version of the Azure Resource Manager common-types to use for refs in emitte
 
 #### `@armLibraryNamespace`
 
-`@armLibraryNamespace` designates a namespace as containign Azure Resource Manager Provider information.
+`@armLibraryNamespace` designates a namespace as containing Azure Resource Manager Provider information.
+This is used for library namespaces that define reusable ARM resource types that can be shared
+across multiple provider specifications.
 
 ```typespec
 @Azure.ResourceManager.armLibraryNamespace
@@ -171,8 +173,9 @@ namespace Microsoft.ContosoService;
 
 #### `@armProviderNameValue`
 
-`@armResourceType` sets the value fo the decorated string
-property to the type of the Azure Resource Manager resource.
+`@armProviderNameValue` sets the provider namespace value on operations.
+It is used internally to inject the correct provider namespace path segment
+for resource operations in auto-generated routes.
 
 ```typespec
 @Azure.ResourceManager.armProviderNameValue
@@ -188,6 +191,11 @@ None
 
 #### `@armResourceAction`
 
+Marks the operation as a custom action on a specific Azure Resource Manager resource type.
+This decorator associates a POST action operation with its resource,
+identifying the semantics of the operation as a resource action over a specific resource for documentation,
+resource validation, and use by downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceAction(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -224,7 +232,9 @@ Marks the operation as being a check existence (HEAD) operation
 
 #### `@armResourceCollectionAction`
 
-Marks the operation as being a collection action
+Marks the operation as being a collection action that is not associated with a specific resource instance.
+Collection actions are operations that act on a resource collection rather than a single resource,
+such as `checkNameAvailability` or provider-level actions.
 
 ```typespec
 @Azure.ResourceManager.armResourceCollectionAction
@@ -240,6 +250,10 @@ None
 
 #### `@armResourceCreateOrUpdate`
 
+Marks the operation as a create or update (PUT) operation for a specific Azure Resource Manager resource type.
+This decorator identifies the semantics of the operation as a CreateOrReplace lifecycle operation over a particular resource,
+for use in documentation, resource validation, and downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceCreateOrUpdate(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -257,6 +271,10 @@ None
 
 #### `@armResourceDelete`
 
+Marks the operation as a delete (DELETE) operation for a specific Azure Resource Manager resource type.
+This decorator identifies the operation as a Delete lifecycle operation over the resource for us in documentation,
+resource validation, and downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceDelete(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -274,6 +292,10 @@ None
 
 #### `@armResourceList`
 
+Marks the operation as a list (GET collection) operation for a specific Azure Resource Manager resource type.
+This decorator identifies the semantics of the operation as a collection list operation over a resource type and a particular scope for documentation,
+resource validation, and downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceList(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -325,6 +347,10 @@ individually tagged
 
 #### `@armResourceRead`
 
+Marks the operation as a read (GET) operation for a specific Azure Resource Manager resource type.
+This decorator identifies the semantics of the operation as a Read lifecycle operation over a particular resource,
+for use in documentation, resource validation, and downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceRead(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -342,6 +368,10 @@ individually tagged
 
 #### `@armResourceUpdate`
 
+Marks the operation as an update (PATCH) operation for a specific Azure Resource Manager resource type.
+This decorator identifies the operation as an Update lifecycle operation over the resource for use in documentation,
+resource validation, and downstream emitters.
+
 ```typespec
 @Azure.ResourceManager.armResourceUpdate(resourceModel: Model, resourceName?: valueof string)
 ```
@@ -360,7 +390,8 @@ individually tagged
 #### `@armVirtualResource`
 
 This decorator is used on Azure Resource Manager resources that are not based on
-Azure.ResourceManager common types.
+Azure.ResourceManager common types. It marks a model as an ARM virtual resource,
+which is useful for defining the scope of resources used only as parents for child resources, or scopes for extension resources.
 
 ```typespec
 @Azure.ResourceManager.armVirtualResource(provider?: valueof string)
@@ -450,10 +481,11 @@ None
 
 #### `@resourceBaseType`
 
-This decorator sets the base type of the given resource.
+This decorator sets the base type of the given resource, indicating where in the
+Azure Resource Manager hierarchy the resource is located.
 
 ```typespec
-@Azure.ResourceManager.resourceBaseType(baseTypeIt: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension")
+@Azure.ResourceManager.resourceBaseType(baseType: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension")
 ```
 
 ##### Target
@@ -462,9 +494,9 @@ This decorator sets the base type of the given resource.
 
 ##### Parameters
 
-| Name       | Type                                                                         | Description                                                                                                            |
-| ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| baseTypeIt | `"Tenant" \| "Subscription" \| "ResourceGroup" \| "Location" \| "Extension"` | The built-in parent of the resource, this can be "Tenant", "Subscription", "ResourceGroup", "Location", or "Extension" |
+| Name     | Type                                                                         | Description                                                                                                            |
+| -------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| baseType | `"Tenant" \| "Subscription" \| "ResourceGroup" \| "Location" \| "Extension"` | The built-in parent of the resource, this can be "Tenant", "Subscription", "ResourceGroup", "Location", or "Extension" |
 
 #### `@resourceGroupResource`
 

packages/typespec-azure-resource-manager/generated-defs/Azure.ResourceManager.ts

@@ -18,18 +18,19 @@ export interface ResourceOperationOptions {
 }
 
 /**
- * Marks the operation as being a collection action
+ * Marks the operation as being a collection action that is not associated with a specific resource instance.
+ * Collection actions are operations that act on a resource collection rather than a single resource,
+ * such as `checkNameAvailability` or provider-level actions.
  */
 export type ArmResourceCollectionActionDecorator = (
   context: DecoratorContext,
   target: Operation,
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- * `@armResourceType` sets the value fo the decorated string
- * property to the type of the Azure Resource Manager resource.
- *
- * @param resource The resource to get the type of
+ * `@armProviderNameValue` sets the provider namespace value on operations.
+ * It is used internally to inject the correct provider namespace path segment
+ * for resource operations in auto-generated routes.
  */
 export type ArmProviderNameValueDecorator = (
   context: DecoratorContext,
@@ -70,7 +71,6 @@ export type IdentifiersDecorator = (
  *  namespace Microsoft.ContosoService;
  * ```
  * @param providerNamespace Provider namespace
- * @param libraryNamespaces a library namespace containing types for this namespace
  */
 export type ArmProviderNamespaceDecorator = (
   context: DecoratorContext,
@@ -91,7 +91,9 @@ export type UseLibraryNamespaceDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- * `@armLibraryNamespace` designates a namespace as containign Azure Resource Manager Provider information.
+ * `@armLibraryNamespace` designates a namespace as containing Azure Resource Manager Provider information.
+ * This is used for library namespaces that define reusable ARM resource types that can be shared
+ * across multiple provider specifications.
  *
  * @example
  * ```typespec
@@ -189,8 +191,10 @@ export type ExtensionResourceDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as a custom action on a specific Azure Resource Manager resource type.
+ * This decorator associates a POST action operation with its resource,
+ * identifying the semantics of the operation as a resource action over a specific resource for documentation,
+ * resource validation, and use by downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -203,8 +207,9 @@ export type ArmResourceActionDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as a create or update (PUT) operation for a specific Azure Resource Manager resource type.
+ * This decorator identifies the semantics of the operation as a CreateOrReplace lifecycle operation over a particular resource,
+ * for use in documentation, resource validation, and downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -217,8 +222,9 @@ export type ArmResourceCreateOrUpdateDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as a read (GET) operation for a specific Azure Resource Manager resource type.
+ * This decorator identifies the semantics of the operation as a Read lifecycle operation over a particular resource,
+ * for use in documentation, resource validation, and downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -231,8 +237,9 @@ export type ArmResourceReadDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as an update (PATCH) operation for a specific Azure Resource Manager resource type.
+ * This decorator identifies the operation as an Update lifecycle operation over the resource for use in documentation,
+ * resource validation, and downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -245,8 +252,9 @@ export type ArmResourceUpdateDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as a delete (DELETE) operation for a specific Azure Resource Manager resource type.
+ * This decorator identifies the operation as a Delete lifecycle operation over the resource for us in documentation,
+ * resource validation, and downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -259,8 +267,9 @@ export type ArmResourceDeleteDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- *
- *
+ * Marks the operation as a list (GET collection) operation for a specific Azure Resource Manager resource type.
+ * This decorator identifies the semantics of the operation as a collection list operation over a resource type and a particular scope for documentation,
+ * resource validation, and downstream emitters.
  *
  * @param resourceModel Resource model
  * @param resourceName Optional. The name of the resource. If not provided, the name of the resource model will be used.
@@ -326,9 +335,9 @@ export type ArmCommonTypesVersionDecorator = (
 
 /**
  * This decorator is used on Azure Resource Manager resources that are not based on
- * Azure.ResourceManager common types.
+ * Azure.ResourceManager common types. It marks a model as an ARM virtual resource,
+ * which is useful for defining the scope of resources used only as parents for child resources, or scopes for extension resources.
  *
- * @param propertiesType : The type of the resource properties.
  * @param provider Optional. The resource provider namespace for the virtual resource.
  */
 export type ArmVirtualResourceDecorator = (
@@ -338,14 +347,15 @@ export type ArmVirtualResourceDecorator = (
 ) => DecoratorValidatorCallbacks | void;
 
 /**
- * This decorator sets the base type of the given resource.
+ * This decorator sets the base type of the given resource, indicating where in the
+ * Azure Resource Manager hierarchy the resource is located.
  *
- * @param baseTypeIt The built-in parent of the resource, this can be "Tenant", "Subscription", "ResourceGroup", "Location", or "Extension"
+ * @param baseType The built-in parent of the resource, this can be "Tenant", "Subscription", "ResourceGroup", "Location", or "Extension"
  */
 export type ResourceBaseTypeDecorator = (
   context: DecoratorContext,
   target: Model,
-  baseTypeIt: Type,
+  baseType: Type,
 ) => DecoratorValidatorCallbacks | void;
 
 export type AzureResourceManagerDecorators = {

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

@@ -92,7 +92,7 @@ interface NspConfigurationOperations<
   ResourceParameter extends {} = NspConfigurationNameParameter<NspConfigurationKeyName>
 > {
   /**
-   * @dev List the network security perimeter configurations to a resource
+   * List the network security perimeter configurations to a resource
    * @template ParentResource the parent resource of the NspConfiguration
    * @template Resource Optional. The NspConfiguration resource being listed
    * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -127,7 +127,7 @@ interface NspConfigurationOperations<
   >;
 
   /**
-   * @dev List the network security parameter configuration for a resource without pagination - this should only be used for legacy operations
+   * List the network security parameter configuration for a resource without pagination - this should only be used for legacy operations
    * @template ParentResource the parent resource of the NspConfiguration
    * @template Resource Optional. The NspConfiguration resource being listed
    * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -162,7 +162,7 @@ interface NspConfigurationOperations<
   >;
 
   /**
-   * @dev GET a network security perimeter configuration for a particular resource
+   * GET a network security perimeter configuration for a particular resource
    * @template ParentResource the parent resource of the NspConfiguration
    * @template Resource the NspConfiguration resource being read
    * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -196,7 +196,7 @@ interface NspConfigurationOperations<
   >;
 
   /**
-   * @dev Perform an action on a network security perimeter configuration for a particular resource
+   * Perform an action on a network security perimeter configuration for a particular resource
    * @template ParentResource the parent resource of the NspConfiguration
    * @template Request The request body type
    * @template Response The success response for the read operation
@@ -238,7 +238,7 @@ interface NspConfigurationOperations<
   ): Response | Error;
 
   /**
-   * @dev Perform an action on a network security perimeter configuration for a particular resource
+   * Perform an action on a network security perimeter configuration for a particular resource
    * @template ParentResource the parent resource of the NspConfiguration
    * @template Request The request body type
    * @template Response The success response for the read operation

packages/typespec-azure-resource-manager/lib/common-types/types.tsp

@@ -344,8 +344,7 @@ union createdByType {
   string,
 }
 
-/** @dev Resource Identity Type */
-@doc("")
+/** Resource Identity Type */
 union ResourceIdentityType {
   SystemAssigned: "SystemAssigned",
 }
@@ -369,7 +368,7 @@ model Identity {
   type?: ResourceIdentityType;
 }
 
-/** @dev Properties of a KeyVault */
+/** Properties of a KeyVault */
 model KeyVaultProperties {
   /** Key vault uri to access the encryption key. */
   keyIdentifier?: string;