@azure-tools/typespec-azure-resource-manager 0.30.0-dev.6 → 0.30.0-dev.7

package/lib/arm.foundations.tsp

@@ -4,6 +4,9 @@ using TypeSpec.Versioning;
 
 namespace Azure.ResourceManager.Foundations;
 
+/**
+ * A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.
+ */
 @armCommonDefinition
 @doc("""
 A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.
@@ -90,6 +93,9 @@ enum ActionType {
   Internal,
 }
 
+/**
+ * Localized display information for and operation.
+ */
 @armCommonDefinition
 @doc("Localized display information for and operation.")
 model OperationDisplay {
@@ -112,6 +118,9 @@ model OperationDisplay {
   description?: string;
 }
 
+/**
+ * The current status of an async operation.
+ */
 @armCommonDefinition
 @doc("The current status of an async operation.")
 model OperationStatusResult {
@@ -142,6 +151,9 @@ model OperationStatusResult {
   error?: ErrorDetail;
 }
 
+/**
+ * The error detail.
+ */
 @armCommonDefinition
 @doc("The error detail.")
 model ErrorDetail {
@@ -168,6 +180,10 @@ model ErrorDetail {
   additionalInfo?: ErrorAdditionalInfo[];
 }
 
+/**
+ * Base parameters for a resource.
+ * @template TResource The type of the resource.
+ */
 @resourceBaseParametersOf(TResource)
 model BaseParameters<TResource extends ArmResource> {
   ...ApiVersionParameter;
@@ -181,31 +197,44 @@ model BaseParameters<TResource extends ArmResource> {
   ...ResourceUriParameter;
 }
 
-// The static parameters for a tenant-based resource
+/**
+ * The static parameters for a tenant-based resource
+ */
 model TenantBaseParameters {
   ...ApiVersionParameter;
 }
 
-// The static parameters for a subscription based resource
+/**
+ * The static parameters for a subscription based resource
+ */
 model SubscriptionBaseParameters is TenantBaseParameters {
   ...SubscriptionIdParameter;
 }
 
-// The static parameters for a location-based resource
+/**
+ * The static parameters for a location-based resource
+ */
 model LocationBaseParameters is SubscriptionBaseParameters {
   ...LocationParameter;
 }
 
-// The static parameters for a resource-group based resource
+/**
+ * The static parameters for a resource-group based resource
+ */
 model ResourceGroupBaseParameters is SubscriptionBaseParameters {
   ...ResourceGroupParameter;
 }
 
-// The static parameters for an extension resource
+/**
+ * The static parameters for an extension resource
+ */
 model ExtensionBaseParameters is TenantBaseParameters {
   ...ResourceUriParameter;
 }
 
+/**
+ * The resource management error additional info.
+ */
 @armCommonDefinition
 @doc("The resource management error additional info.")
 model ErrorAdditionalInfo {
@@ -229,6 +258,9 @@ model ArmTagsProperty {
   tags?: Record<string>;
 }
 
+/**
+ * The kind of entity that created the resource.
+ */
 // NOTE: This is how the enum is named in types.json
 @doc("The kind of entity that created the resource.")
 enum createdByType {
@@ -238,6 +270,9 @@ enum createdByType {
   Key,
 }
 
+/**
+ * Metadata pertaining to creation and last modification of the resource.
+ */
 @armCommonDefinition("systemData")
 @doc("Metadata pertaining to creation and last modification of the resource.")
 model SystemData {
@@ -266,6 +301,9 @@ model SystemData {
   lastModifiedAt?: plainDate;
 }
 
+/**
+ * The properties of the managed service identities assigned to this resource.
+ */
 @armCommonDefinition("ManagedServiceIdentity", "v4", "managedidentity.json")
 @doc("The properties of the managed service identities assigned to this resource.")
 model ManagedIdentityProperties {
@@ -284,6 +322,9 @@ model ManagedIdentityProperties {
   userAssignedIdentities?: Record<UserAssignedIdentity>;
 }
 
+/**
+ * The properties of the service-assigned identity associated with this resource.
+ */
 @armCommonDefinition("SystemAssignedServiceIdentity", "v4", "managedidentity.json")
 @doc("The properties of the service-assigned identity associated with this resource.")
 model ManagedSystemIdentityProperties {
@@ -299,6 +340,9 @@ model ManagedSystemIdentityProperties {
   type: ManagedSystemIdentityType;
 }
 
+/**
+ * A managed identity assigned by the user.
+ */
 @doc("A managed identity assigned by the user.")
 model UserAssignedIdentity {
   @doc("The active directory client identifier for this principal.")
@@ -308,6 +352,9 @@ model UserAssignedIdentity {
   principalId?: string;
 }
 
+/**
+ * The kind of managed identity assigned to this resource.
+ */
 @doc("The kind of managed identity assigned to this resource.")
 enum ManagedIdentityType {
   None,
@@ -316,21 +363,32 @@ enum ManagedIdentityType {
   SystemAndUserAssigned: "SystemAssigned, UserAssigned",
 }
 
+/**
+ * The kind of managemed identity assigned to this resource.
+ */
 @doc("The kind of managemed identity assigned to this resource.")
 enum ManagedSystemIdentityType {
   None,
   SystemAssigned,
 }
 
-// Defines a properties type used to create named resource update models.
-// This type is not used directly, it is referenced by ResourceUpdateModel<T>.
+/**
+ * Defines a properties type used to create named resource update models.
+ * This type is not used directly, it is referenced by ResourceUpdateModel.
+ * @template TResource The type of the resource.
+ * @template TProperties The type of the properties.
+ */
 @doc("The updatable properties of the {name}.", TResource)
 @friendlyName("{name}UpdateProperties", TResource)
 model ResourceUpdateModelProperties<TResource extends ArmResource, TProperties extends object>
   is OptionalProperties<UpdateableProperties<TProperties>>;
 
-// Defines a model type used to create named resource update models
-//   e.g. `model MyResourceUpdate is ResourceUpdate<MyResourceProperties> {}`
+/**
+ * Defines a model type used to create named resource update models
+ * e.g. `model MyResourceUpdate is ResourceUpdate<MyResourceProperties> {}`
+ * @template TResource The type of the resource.
+ * @template TProperties The type of the properties.
+ */
 @doc("The type used for update operations of the {name}.", TResource)
 @friendlyName("{name}Update", TResource)
 @omitIfEmpty("properties")
@@ -340,6 +398,10 @@ model ResourceUpdateModel<TResource extends ArmResource, TProperties extends obj
   properties?: ResourceUpdateModelProperties<TResource, TProperties>;
 }
 
+/**
+ * The type used for updating tags in resources.
+ * @template TResource The type of the resource.
+ */
 @doc("The type used for updating tags in {name} resources.", TResource)
 @friendlyName("{name}TagsUpdate", TResource)
 model TagsUpdateModel<TResource extends ArmResource> {
@@ -350,25 +412,43 @@ model TagsUpdateModel<TResource extends ArmResource> {
 
 alias TenantParentScope<TResource extends ArmResource> = TenantScope<TResource>;
 
-// Parameter model for listing a resource at the tenant scope
+/**
+ * Parameter model for listing a resource at the tenant scope
+ * @template TResource The type of the resource.
+ */
 model TenantScope<TResource extends ArmResource>
   is ResourceParentParameters<TResource, TenantBaseParameters>;
 
-// Parameter model for listing a resource at the subscription scope
+/**
+ * Parameter model for listing a resource at the subscription scope
+ * @template TResource The type of the resource.
+ */
 model SubscriptionScope<TResource extends ArmResource>
   is ResourceParentParameters<TResource, SubscriptionBaseParameters>;
 
-// Parameter model for listing a resource at the location scope
+/**
+ * Parameter model for listing a resource at the location scope
+ * @template TResource The type of the resource.
+ */
 model LocationScope<TResource extends ArmResource>
   is ResourceParentParameters<TResource, LocationBaseParameters>;
 
-// Parameter model for listing an extension resource
+/**
+ * Parameter model for listing an extension resource
+ * @template TResource The type of the resource.
+ */
 model ExtensionScope<TResource extends ArmResource>
   is ResourceParentParameters<TResource, ExtensionBaseParameters>;
 
-// Parameter model for listing a resource at the resource group scope
+/**
+ * Parameter model for listing a resource at the resource group scope
+ * @template TResource The type of the resource.
+ */
 model ResourceGroupScope<TResource extends ArmResource> is ResourceParentParameters<TResource>;
 
+/**
+ * Details of the resource plan.
+ */
 @doc("Details of the resource plan.")
 @armCommonDefinition("Plan")
 model ResourcePlanType {
@@ -388,6 +468,9 @@ model ResourcePlanType {
   version?: string;
 }
 
+/**
+ * The SKU (Stock Keeping Unit) assigned to this resource.
+ */
 @doc("The SKU (Stock Keeping Unit) assigned to this resource.")
 @armCommonDefinition("Sku")
 model ResourceSkuType {
@@ -407,6 +490,9 @@ model ResourceSkuType {
   capacity?: int32;
 }
 
+/**
+ * Available service tiers for the SKU.
+ */
 @doc("Available service tiers for the SKU.")
 enum SkuTier {
   Free,
@@ -415,6 +501,11 @@ enum SkuTier {
   Premium,
 }
 
+/**
+ * The type used for update operations of the resource.
+ * @template TResource The type of the resource.
+ * @template TProperties The type of the properties.
+ */
 @doc("The type used for update operations of the {name}.", TResource)
 @friendlyName("{name}Update", TResource)
 model ProxyResourceUpdateModel<TResource extends ArmResource, TProperties extends object> {
@@ -455,6 +546,9 @@ model Operation {
   actionType?: ActionType;
 }
 
+/**
+ * The default operationId parameter type.
+ */
 @doc("The default operationId parameter type.")
 model OperationIdParameter {
   @path
@@ -464,6 +558,9 @@ model OperationIdParameter {
   operationId: string;
 }
 
+/**
+ * The check availability request body.
+ */
 @armCommonDefinition
 @doc("The check availability request body.")
 model CheckNameAvailabilityRequest {
@@ -474,12 +571,18 @@ model CheckNameAvailabilityRequest {
   type?: string;
 }
 
+/**
+ * Possible reasons for a name not being available.
+ */
 @doc("Possible reasons for a name not being available.")
 enum CheckNameAvailabilityReason {
   Invalid,
   AlreadyExists,
 }
 
+/**
+ * The check availability result.
+ */
 @armCommonDefinition
 @doc("The check availability result.")
 model CheckNameAvailabilityResponse {

package/lib/arm.tsp

@@ -25,6 +25,9 @@ using Azure.ResourceManager.Foundations;
 @versioned(Azure.ResourceManager.Versions)
 namespace Azure.ResourceManager;
 
+/**
+ * Supported versions of Azure.ResourceManager building blocks.
+ */
 enum Versions {
   @useDependency(Azure.Core.Versions.v1_0_Preview_1)
   v1_0_Preview_1: "1.0-preview.1",

package/lib/interfaces.tsp

@@ -75,6 +75,8 @@ interface TrackedResourceOperations<
  *   `/subscriptions/{id}/resourcegroups/{rg}/providers/Microsoft.XXX/...`
  *
  * This is the most common API pattern for Proxy Resources to use.
+ * @template TResource the ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
  */
 interface ProxyResourceOperations<
   TResource extends ArmResource,
@@ -93,6 +95,8 @@ interface ProxyResourceOperations<
  *   `/providers/Microsoft.XXX/...`
  *
  * This is the most common API pattern for Tenant Resources to use.
+ * @template TResource the ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
  */
 interface TenantResourceOperations<TResource extends ArmResource, TProperties extends object>
   extends TenantResourceRead<TResource>,
@@ -101,6 +105,13 @@ interface TenantResourceOperations<TResource extends ArmResource, TProperties ex
     TenantResourceDelete<TResource>,
     TenantResourceListByParent<TResource> {}
 
+/**
+ * A composite interface for resources that have CRUD operations.
+ * @template TResource The ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
+ * @template TBaseParameters The http parameters that are part of the request
+ * @template TPatchModel The model used for PATCH operations
+ */
 interface ResourceInstanceOperations<
   TResource extends ArmResource,
   TProperties extends object,
@@ -112,15 +123,31 @@ interface ResourceInstanceOperations<
     ResourceUpdate<TResource, TProperties, TBaseParameters>,
     ResourceDelete<TResource, TBaseParameters> {}
 
+/**
+ * A composite interface for resource collections.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 interface ResourceCollectionOperations<
   TResource extends ArmResource,
   TBaseParameters = BaseParameters<TResource>
 > extends ResourceListByParent<TResource, TBaseParameters>, ResourceListBySubscription<TResource> {}
 
+/**
+ * An interface for resources with can be listed by subscription.
+ * @template TResource The ArmResource that provides these operations
+ */
 interface ResourceListBySubscription<TResource extends ArmResource> {
   listBySubscription is ArmListBySubscription<TResource>;
 }
 
+/**
+ * An interface for resources which can be listed by parent.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ * @template TParentName The name of the parent resource
+ * @template TParentFriendlyName The friendly name of the parent resource
+ */
 interface ResourceListByParent<
   TResource extends ArmResource,
   TBaseParameters = BaseParameters<TResource>,
@@ -135,10 +162,20 @@ interface ResourceListByParent<
   >;
 }
 
+/**
+ * A composite interface for resources that include a GET operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 interface ResourceRead<TResource extends ArmResource, TBaseParameters = BaseParameters<TResource>> {
   get is ArmResourceRead<TResource, TBaseParameters>;
 }
 
+/**
+ * A composite interface for resources that include a synchronous create or update operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 interface ResourceCreateSync<
   TResource extends ArmResource,
   TBaseParameters = BaseParameters<TResource>
@@ -146,6 +183,11 @@ interface ResourceCreateSync<
   createOrUpdate is ArmResourceCreateOrUpdateSync<TResource, TBaseParameters>;
 }
 
+/**
+ * A composite interface for resources that include a long-running create or update operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 interface ResourceCreateAsync<
   TResource extends ArmResource,
   TBaseParameters = BaseParameters<TResource>
@@ -153,6 +195,11 @@ interface ResourceCreateAsync<
   createOrUpdate is ArmResourceCreateOrUpdateAsync<TResource, TBaseParameters>;
 }
 
+/**
+ * A composite interface for resources that include a long-running delete operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 @doc("Delete a resource using the asynchronous call pattern")
 interface ResourceDeleteAsync<
   TResource extends ArmResource,
@@ -161,6 +208,11 @@ interface ResourceDeleteAsync<
   delete is ArmResourceDeleteAsync<TResource, TBaseParameters>;
 }
 
+/**
+ * A composite interface for resources that include a synchronous delete operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 @doc("Delete a resource")
 interface ResourceDeleteSync<
   TResource extends ArmResource,
@@ -169,6 +221,12 @@ interface ResourceDeleteSync<
   delete is ArmResourceDeleteSync<TResource, TBaseParameters>;
 }
 
+/**
+ * A composite interface for resources that include a long-running update operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 @doc("Asynchronous resource update")
 interface ResourceUpdateAsync<
   TResource extends ArmResource,
@@ -182,6 +240,12 @@ interface ResourceUpdateAsync<
   >;
 }
 
+/**
+ * A composite interface for resources that include a synchronous update operation.
+ * @template TResource The ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
+ * @template TBaseParameters The http parameters that are part of the request
+ */
 @doc("Synchronous resource update")
 interface ResourceUpdateSync<
   TResource extends ArmResource,
@@ -195,6 +259,11 @@ interface ResourceUpdateSync<
   >;
 }
 
+/**
+ * A composite interface for resources that includes CRUD operations.
+ * @template TResource The ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
+ */
 interface ExtensionResourceInstanceOperations<
   TResource extends ArmResource,
   TProperties extends object
@@ -204,9 +273,18 @@ interface ExtensionResourceInstanceOperations<
     ExtensionResourceUpdate<TResource, TProperties>,
     ExtensionResourceDelete<TResource> {}
 
+/**
+ * A composite interface for resource collections that include a paginated list operation.
+ * @template TResource The ArmResource that provides these operations
+ */
 interface ExtensionResourceCollectionOperations<TResource extends ArmResource>
   extends ExtensionResourceList<TResource> {}
 
+/**
+ * A composite interface for resources that include CRUD and list operations.
+ * @template TResource The ArmResource that provides these operations
+ * @template TProperties RP-specific property bag for the resource
+ */
 interface ExtensionResourceOperations<TResource extends ArmResource, TProperties extends object>
   extends ExtensionResourceInstanceOperations<TResource, TProperties>,
     ExtensionResourceCollectionOperations<TResource> {}

package/lib/models.tsp

@@ -72,6 +72,10 @@ model KeysOf<TResource> {}
 @copyResourceKeyParameters("parent")
 model ParentKeysOf<TResource> {}
 
+/**
+ * Model describing the provider namespace.
+ * @template TResource The resource provided by the namespace.
+ */
 model ProviderNamespace<TResource> {
   @path
   @segment("providers")
@@ -219,7 +223,7 @@ model ResourceKind {
 
 /**
  * Paged response containing resources
- * @template TResopurce The type of the values returned in the paged response (must be a resource)
+ * @template TResource The type of the values returned in the paged response (must be a resource)
  */
 @doc("The response of a {name} list operation.", TResource)
 @friendlyName("{name}ListResult", TResource)

package/lib/operations.tsp

@@ -25,6 +25,9 @@ op ArmListBySubscription<TResource extends ArmResource>(
 /**
  * A resource list operation, at the scope of the resource's parent
  * @template TResource the resource being patched
+ * @template TBaseParameters Optional. Allows overriding the operation parameters
+ * @template TParentName Optional. The name of the parent resource
+ * @template TParentFriendlyName Optional. The friendly name of the parent resource
  */
 @get
 @autoRoute
@@ -240,6 +243,11 @@ op ArmResourceDeleteAsync<
   | ArmDeletedNoContentResponse
   | ErrorResponse;
 
+/**
+ * Delete a resource synchronously
+ * @template TResource The resource being deleted
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @doc("Delete a {name}", TResource)
 @armResourceDelete(TResource)
@@ -251,6 +259,13 @@ op ArmResourceDeleteSync<
   ...ResourceInstanceParameters<TResource, TBaseParameters>
 ): ArmDeletedResponse | ArmDeletedNoContentResponse | ErrorResponse;
 
+/**
+ * A long-running resource action.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TResponse The response model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @extension("x-ms-long-running-operation", true)
 @extension(
@@ -274,6 +289,13 @@ op ArmResourceActionAsync<
   body: TRequest
 ): ArmAcceptedLroResponse | ArmResponse<TResponse> | ErrorResponse;
 
+/**
+ * A synchronous resource action.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TResponse The response model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @armResourceAction(TResource)
 @post
@@ -290,6 +312,12 @@ op ArmResourceActionSync<
   body: TRequest
 ): ArmResponse<TResponse> | ErrorResponse;
 
+/**
+ * A long-running resource action that returns no content.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @extension("x-ms-long-running-operation", true)
 @extension(
@@ -312,6 +340,12 @@ op ArmResourceActionNoContentAsync<
   body: TRequest
 ): ArmAcceptedLroResponse | ArmNoContentResponse<"Action completed successfully."> | ErrorResponse;
 
+/**
+ * A synchronous resource action that returns no content.
+ * @template TResource The resource being acted upon
+ * @template TRequest The request model for the action
+ * @template TBaseParameters Optional. Allows overriding the parameters for the operation
+ */
 @autoRoute
 @armResourceAction(TResource)
 @post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-tools/typespec-azure-resource-manager",
-  "version": "0.30.0-dev.6",
+  "version": "0.30.0-dev.7",
   "author": "Microsoft Corporation",
   "description": "TypeSpec Azure Resource Manager library",
   "homepage": "https://azure.github.io/typespec-azure",