@azure-tools/typespec-azure-resource-manager 0.70.0-dev.2 → 0.70.0-dev.4

package/lib/decorators.tsp

@@ -19,7 +19,6 @@ namespace Azure.ResourceManager;
  * ```
  *
  * @param providerNamespace Provider namespace
- * @param libraryNamespaces a library namespace containing types for this namespace
  *
  */
 extern dec armProviderNamespace(target: Namespace, providerNamespace?: valueof string);
@@ -32,7 +31,9 @@ extern dec armProviderNamespace(target: Namespace, providerNamespace?: valueof s
 extern dec useLibraryNamespace(target: Namespace, ...namespaces: Namespace[]);
 
 /**
- * `@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
  *
@@ -110,18 +111,25 @@ extern dec resourceGroupResource(target: Model);
 extern dec extensionResource(target: Model);
 
 /**
- * `@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.
  */
 extern dec armProviderNameValue(target: Operation);
 
 /**
- * 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.
  */
 extern dec armResourceCollectionAction(target: Operation);
 
 /**
+ * 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.
  */
@@ -132,6 +140,10 @@ extern dec armResourceAction(
 );
 
 /**
+ * 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.
  */
@@ -142,12 +154,20 @@ extern dec armResourceCreateOrUpdate(
 );
 
 /**
+ * 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.
  */
 extern dec armResourceRead(target: Operation, resourceModel: Model, resourceName?: valueof string);
 
 /**
+ * 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.
  */
@@ -158,6 +178,10 @@ extern dec armResourceUpdate(
 );
 
 /**
+ * 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.
  */
@@ -168,6 +192,10 @@ extern dec armResourceDelete(
 );
 
 /**
+ * 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.
  */
@@ -242,21 +270,22 @@ extern dec armCommonTypesVersion(
 
 /**
  * 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.
  */
 extern dec armVirtualResource(target: Model, provider?: valueof string);
 
 /**
- * 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"
  */
 extern dec resourceBaseType(
   target: Model,
-  baseTypeIt: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension"
+  baseType: "Tenant" | "Subscription" | "ResourceGroup" | "Location" | "Extension"
 );
 
 /**

package/lib/extension/operations.tsp

@@ -176,7 +176,7 @@ op CreateOrReplaceSync<
 >;
 
 /**
- * @dev A long-running resource CreateOrUpdate (PUT)
+ * A long-running resource CreateOrUpdate (PUT)
  * @template TargetResource the target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource the resource being created or replaced
  * @template LroHeaders Optional.  Allows overriding the lro headers returned on resource create
@@ -288,7 +288,7 @@ op CustomPatchSync<
 >;
 
 /**
- * @dev Delete a resource asynchronously
+ * Delete a resource asynchronously
  * @template TargetResource The target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource The resource being deleted
  * @template Response The response type for the operation
@@ -314,7 +314,7 @@ op DeleteAsyncBase<
   | Error;
 
 /**
- * @dev Delete a resource asynchronously.
+ * Delete a resource asynchronously.
  * @template TargetResource The target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource The resource being deleted
  * @template LroHeaders Optional. Allows overriding the headers in the Accepted response
@@ -351,7 +351,7 @@ op DeleteAsync<
 >;
 
 /**
- * @dev Delete a resource asynchronously
+ * Delete a resource asynchronously
  * @template TargetResource The target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource The resource being deleted
  * @template LroHeaders Optional. Allows overriding the headers returned in the Accepted response
@@ -444,7 +444,7 @@ op ActionAsyncBase<
 ): Response | Error;
 
 /**
- * @dev A long-running resource action.
+ * A long-running resource action.
  * @template TargetResource The target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource The resource being acted upon
  * @template Request The request model for the action
@@ -459,6 +459,7 @@ op ActionAsyncBase<
 @extensionResourceOperation(TargetResource, ExtensionResource, "action", OverrideResourceName)
 @returnsDoc("Azure operation completed successfully.")
 @enforceConstraint(ExtensionResource, Foundations.Resource)
+@doc("")
 op ActionAsync<
   TargetResource extends Foundations.SimpleResource,
   ExtensionResource extends Foundations.SimpleResource,
@@ -520,7 +521,7 @@ op ActionSync<
 ): Response | Error;
 
 /**
- * @dev A long-running resource action that returns no content.
+ * A long-running resource action that returns no content.
  * @template TargetResource The target resource, e.g. Extension.Subscription or Extension.ManagementGroup or Extension.ResourceGroup
  * @template ExtensionResource The resource being acted upon
  * @template Request The request model for the action
@@ -535,6 +536,7 @@ op ActionSync<
 @enforceConstraint(TargetResource, Foundations.Resource)
 @enforceConstraint(ExtensionResource, Foundations.Resource)
 @post
+@doc("")
 op ActionNoResponseContentAsync<
   TargetResource extends Foundations.SimpleResource,
   ExtensionResource extends Foundations.SimpleResource,

package/lib/foundations/arm.foundations.tsp

@@ -140,29 +140,37 @@ alias TenantParentScope<Resource extends Foundations.SimpleResource> = TenantSco
  * Parameter model for listing a resource at the tenant scope
  * @template Resource The type of the resource.
  */
-model TenantScope<Resource extends Foundations.SimpleResource>
-  is ResourceParentParameters<Resource, TenantBaseParameters>;
+model TenantScope<Resource extends Foundations.SimpleResource> is ResourceParentParameters<
+  Resource,
+  TenantBaseParameters
+>;
 
 /**
  * Parameter model for listing a resource at the subscription scope
  * @template Resource The type of the resource.
  */
-model SubscriptionScope<Resource extends Foundations.SimpleResource>
-  is ResourceParentParameters<Resource, SubscriptionBaseParameters>;
+model SubscriptionScope<Resource extends Foundations.SimpleResource> is ResourceParentParameters<
+  Resource,
+  SubscriptionBaseParameters
+>;
 
 /**
  * Parameter model for listing a resource at the location scope
  * @template Resource The type of the resource.
  */
-model LocationScope<Resource extends Foundations.SimpleResource>
-  is ResourceParentParameters<Resource, LocationBaseParameters>;
+model LocationScope<Resource extends Foundations.SimpleResource> is ResourceParentParameters<
+  Resource,
+  LocationBaseParameters
+>;
 
 /**
  * Parameter model for listing an extension resource
  * @template Resource The type of the resource.
  */
-model ExtensionScope<Resource extends Foundations.SimpleResource>
-  is ResourceParentParameters<Resource, ExtensionBaseParameters>;
+model ExtensionScope<Resource extends Foundations.SimpleResource> is ResourceParentParameters<
+  Resource,
+  ExtensionBaseParameters
+>;
 
 /**
  * Parameter model for listing a resource at the resource group scope
@@ -240,22 +248,24 @@ op checkNameAvailability<
 ): Response | ErrorResponse;
 
 /**
- * @dev The base template for Azure Resource Manager GET and HEAD Operations.
+ * The base template for Azure Resource Manager GET and HEAD Operations.
  * @template Parameters The parameter object for the operation.
  * @template Response The response or union of responses for success.
  * @template ErrorResponse The error response.
  */
+@doc("")
 op ArmReadOperation<Parameters extends {}, Response extends {}, ErrorResponse extends {}>(
   ...Parameters,
 ): Response | ErrorResponse;
 
 /**
- * @dev The base template for Azure Resource Manager PUT Operations.
+ * The base template for Azure Resource Manager PUT Operations.
  * @template HttpParameters The parameter object for the operation.
  * @template BodyParameter The body parameter
  * @template Response The response or union of responses for success.
  * @template ErrorResponse The error response.
  */
+@doc("")
 op ArmCreateOperation<
   HttpParameters extends {},
   BodyParameter extends {},
@@ -266,12 +276,13 @@ op ArmCreateOperation<
   | ErrorResponse;
 
 /**
- * @dev The base template for Azure Resource Manager PATCH Operations.
+ * The base template for Azure Resource Manager PATCH Operations.
  * @template HttpParameters The parameter object for the operation.
  * @template BodyParameter The body parameter
  * @template Response The response or union of responses for success.
  * @template ErrorResponse The error response.
  */
+@doc("")
 op ArmUpdateOperation<
   HttpParameters extends {},
   BodyParameter extends {},

package/lib/interfaces.tsp

@@ -13,7 +13,7 @@ namespace Azure.ResourceManager;
  */
 interface Operations {
   /**
-   * @dev List the operations for the provider.
+   * List the operations for the provider.
    */
   @tag("Operations")
   @autoRoute
@@ -146,9 +146,10 @@ interface ResourceCollectionOperations<
  */
 interface ResourceListBySubscription<Resource extends Foundations.SimpleResource> {
   /**
-   * @dev List resources by subscription.
+   * List resources by subscription.
    * @template Resource The ArmResource to list.
    */
+  @doc("List {name} resources by subscription ID", Resource)
   listBySubscription is ArmListBySubscription<Resource>;
 }
 
@@ -166,7 +167,7 @@ interface ResourceListByParent<
   ParentFriendlyName extends valueof string = ""
 > {
   /**
-   * @dev List resources by parent.
+   * List resources by parent.
    * @template Resource The ArmResource to list.
    * @template BaseParameters The http parameters that are part of the request
    * @template ParentName The name of the parent resource
@@ -186,10 +187,11 @@ interface ResourceRead<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Retrieve a resource.
+   * Retrieve a resource.
    * @template Resource The ArmResource to retrieve.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Get a {name}", Resource)
   get is ArmResourceRead<Resource, BaseParameters>;
 }
 
@@ -203,10 +205,11 @@ interface ResourceCreateSync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Create or update a resource using the synchronous call pattern.
+   * Create or update a resource using the synchronous call pattern.
    * @template Resource The ArmResource to create or update.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Create a {name}", Resource)
   createOrUpdate is ArmResourceCreateOrReplaceSync<Resource, BaseParameters>;
 }
 
@@ -220,15 +223,16 @@ interface ResourceCreateAsync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Create or update a resource using the asynchronous call pattern.
+   * Create or update a resource using the asynchronous call pattern.
    * @template Resource The ArmResource to create or update.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Create a {name}", Resource)
   createOrUpdate is ArmResourceCreateOrUpdateAsync<Resource, BaseParameters>;
 }
 
 /**
- * @dev A composite interface for resources that include a long-running delete operation.
+ * A composite interface for resources that include a long-running delete operation.
  *      DEPRECATED: Use ResourceDeleteWithoutOkAsync instead
  * @template Resource The ArmResource that provides these operations
  * @template BaseParameters The http parameters that are part of the request
@@ -240,15 +244,17 @@ interface ResourceDeleteAsync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Delete a resource using the asynchronous call pattern.
+   * Delete a resource using the asynchronous call pattern.
    * @template Resource The ArmResource to delete.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Delete a {name}", Resource)
   delete is ArmResourceDeleteAsync<Resource, BaseParameters>;
 }
 
 /**
- * @dev A composite interface for resources that include a synchronous delete operation.
+ * A composite interface for resources that include a long-running delete operation
+ * without returning a final OK response.
  * @template Resource The ArmResource that provides these operations
  * @template BaseParameters The http parameters that are part of the request
  */
@@ -258,10 +264,11 @@ interface ResourceDeleteWithoutOkAsync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Delete a resource using the asynchronous call pattern.
+   * Delete a resource using the asynchronous call pattern.
    * @template Resource The ArmResource to delete.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Delete a {name}", Resource)
   delete is ArmResourceDeleteWithoutOkAsync<Resource, BaseParameters>;
 }
 
@@ -276,15 +283,16 @@ interface ResourceDeleteSync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Delete a resource using the synchronous call pattern.
+   * Delete a resource using the synchronous call pattern.
    * @template Resource The ArmResource to delete.
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Delete a {name}", Resource)
   delete is ArmResourceDeleteSync<Resource, BaseParameters>;
 }
 
 /**
- * @dev A composite interface for resources that include a long-running update operation.
+ * A composite interface for resources that include a long-running update operation.
  * @template Resource The ArmResource that provides these operations
  * @template Properties RP-specific property bag for the resource
  * @template BaseParameters The http parameters that are part of the request
@@ -296,11 +304,12 @@ interface ResourceUpdateAsync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Update a resource using the asynchronous call pattern.
+   * Update a resource using the asynchronous call pattern.
    * @template Resource The ArmResource to update.
    * @template Properties RP-specific property bag for the resource
    * @template BaseParameters The http parameters that are part of the request
    */
+  @doc("Update a {name}", Resource)
   update is ArmCustomPatchAsync<
     Resource,
     ResourceUpdateModel<Resource, Properties>,
@@ -321,13 +330,14 @@ interface ResourceUpdateSync<
   BaseParameters = DefaultBaseParameters<Resource>
 > {
   /**
-   * @dev Update a resource using the synchronous call pattern.
+   * Update a resource using the synchronous call pattern.
    * @template Resource The ArmResource to update.
    * @template Properties RP-specific property bag for the resource
    * @template BaseParameters The http parameters that are part of the request
    */
   #suppress "@typespec/http/deprecated-implicit-optionality" "Legacy"
   @patch(#{ implicitOptionality: true })
+  @doc("Update a {name}", Resource)
   update is ArmCustomPatchSync<Resource, ResourceUpdateModel<Resource, Properties>, BaseParameters>;
 }
 

package/lib/legacy-types/extension.tsp

@@ -215,7 +215,7 @@ interface ExtensionOperations<
   >(...TargetParameters, ...ExtensionInstanceParameters, ...Parameters): Response | ErrorType;
 
   /**
-   * @dev Get a resource
+   * Get a resource
    * @template Resource The resource being read
    * @template Parameters Optional. Additional parameters after the path parameters
    * @template Response Optional. The success response for a get operation.

package/lib/legacy-types/operations.tsp

@@ -246,7 +246,7 @@ interface RoutedOperations<
   >(...ParentParameters, ...ResourceTypeParameter, ...Parameters): Response | OverrideErrorType;
 
   /**
-   * @dev Get a resource
+   * Get a resource
    * @template Resource The resource being read
    * @template Parameters Optional. Additional parameters after the path parameters
    * @template Response Optional. The success response for a get operation.
@@ -434,17 +434,19 @@ interface RoutedOperations<
   ): Response | OverrideErrorType;
 }
 /**
- * @dev DEPRECATED: Use ProviderParameter instead. Get the provider namespace key-value pair
+ * DEPRECATED: Use ProviderParameter instead. Get the provider namespace key-value pair
  * @template Resource Optional.  The resource to get the provider namespace for.
  */
+@doc("")
 model Provider<Resource extends {} = TenantActionScope> {
   ...ProviderNamespace<Resource>;
 }
 
 /**
- * @dev Get the provider namespace key-value pair
+ * Get the provider namespace key-value pair
  * @template Resource The resource to get the provider namespace for.
  */
+@doc("")
 model ProviderParameter<Resource extends {}> {
   ...ProviderNamespace<Resource>;
 }
@@ -709,13 +711,14 @@ op ArmListSinglePageByParent<
 >;
 
 /**
- * @dev The base template for Azure Resource Manager PUT Operations.
+ * The base template for Azure Resource Manager PUT Operations.
  * @template HttpParameters The parameter object for the operation.
  * @template BodyParameter The body parameter
  * @template Response The response or union of responses for success.
  * @template ErrorResponse The error response.
  * @template OptionalRequestBody Optional. Indicates whether the request body is optional
  */
+@doc("")
 op CreateOperation<
   HttpParameters extends {},
   BodyParameter extends {} | void,
@@ -731,13 +734,14 @@ op CreateOperation<
 ): Response | ErrorResponse;
 
 /**
- * @dev The base template for Legacy Azure Resource Manager PATCH Operations.
+ * The base template for Legacy Azure Resource Manager PATCH Operations.
  * @template HttpParameters The parameter object for the operation.
  * @template BodyParameter The body parameter
  * @template Response The response or union of responses for success.
  * @template ErrorResponse The error response.
  * @template OptionalRequestBody Optional. Indicates whether the request body is optional
  */
+@doc("")
 op UpdateOperation<
   HttpParameters extends {},
   BodyParameter extends {} | void,

package/lib/legacy-types/private-endpoints.tsp

@@ -8,7 +8,7 @@ using Azure.ResourceManager.Foundations;
 using Rest;
 
 /**
- * @dev List the private endpoint connections over a resource
+ * List the private endpoint connections over a resource
  * @template ParentResource the parent resource of the PrivateEndpointConnection
  * @template Resource Optional. The PrivateEndpointConnection resource being listed
  * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -39,7 +39,7 @@ op ListSinglePageByParent<
 >;
 
 /**
- * @dev Synchronous PUT operation for a Private endpoint connection to a resource
+ * Synchronous PUT operation for a Private endpoint connection to a resource
  * @template ParentResource the parent resource of the PrivateEndpointConnection
  * @template Resource the PrivateEndpointConnection resource being created or updated
  * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -76,7 +76,7 @@ op CreateOrReplaceSync<
 >;
 
 /**
- * @dev A long-running resource CreateOrUpdate (PUT) for a PrivateEndpointConnection to a resource
+ * A long-running resource CreateOrUpdate (PUT) for a PrivateEndpointConnection to a resource
  * @template ParentResource the parent resource of the PrivateEndpointConnection
  * @template Resource the PrivateEndpointConnection resource being created or updated
  * @template BaseParameters Optional. Allows overriding the operation parameters
@@ -161,7 +161,7 @@ op CustomPatchAsync<
 >;
 
 /**
- * @dev A resource update using a custom PATCH payload (synchronous) to update a PrivateEndpointConnection to a resource
+ * A resource update using a custom PATCH payload (synchronous) to update a PrivateEndpointConnection to a resource
  * @template ParentResource The parent resource of the PrivateEndpointConnection
  * @template Resource Optional. The PrivateEndpointConnection resource being patched
  * @template PatchModel The input model for the PATCH request

package/lib/models.tsp

@@ -340,7 +340,7 @@ model ResourceKindProperty<Type extends string = string> {
 model ResourceListResult<Resource extends Foundations.SimpleResource> is Azure.Core.Page<Resource>;
 
 /**
- * Paged response containing results
+ * Paged response containing custom result types.
  * @template Result The type of the values returned in the paged response
  */
 @doc("The custom response of a list operation.")