@azure-tools/typespec-azure-resource-manager 0.57.0-dev.5 → 0.57.0-dev.6

package/lib/arm.tsp

@@ -28,6 +28,21 @@ namespace Azure.ResourceManager;
 
 /**
  * Supported versions of Azure.ResourceManager building blocks.
+ *
+ * @example
+ * ```typespec
+ * enum Versions {
+ *  @useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
+ *  @useDependency(Azure.Core.Versions.v1_0_Preview_2)
+ *  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
+ *  v2021_10_01_preview: "2021-10-01-preview",
+ *
+ *  @useDependency(Azure.ResourceManager.Versions.v1_0_Preview_1)
+ *  @useDependency(Azure.Core.Versions.v1_0_Preview_2)
+ *  @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
+ *  v2021_11_01: "2021-11-01",
+ * }
+ * ```
  */
 @doc("Supported versions of Azure.ResourceManager building blocks.")
 enum Versions {

package/lib/common-types/types.tsp

@@ -473,6 +473,13 @@ model LocationData {
 
 /**
  * The default api-version parameter type.
+ *
+ * @example
+ * ```typespec
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>;
+ * }
+ * ```
  */
 model ApiVersionParameter {
   /** The API version to use for this operation. */
@@ -493,6 +500,16 @@ model OperationIdParameter {
 
 /**
  * The default location parameter type.
+ *
+ * @example
+ * ```typespec
+ * op employee is ArmProviderActionSync<
+ *  Request = Employee,
+ *  Response = Employee,
+ *  Scope = SubscriptionActionScope,
+ *  Parameters = LocationParameter
+ * >;
+ * ```
  */
 model LocationParameter {
   /** The name of Azure region. */

package/lib/models.tsp

@@ -19,6 +19,18 @@ namespace Azure.ResourceManager;
  * @template SegmentName Override default segment name of the resource.
  * @template NamePattern The RegEx pattern of the name. Default is `^[a-zA-Z0-9-]{3,24}$`.
  * @template Type The type of the name property. Default type is string. However you can pass an union with string values.
+ *
+ * @example
+ * ```typespec
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<
+ *    Resource = Employee,
+ *    KeyName = "employeeName",
+ *    SegmentName = "employees",
+ *    NamePattern = "^[^<>%&:?#/\\\\]+$"
+ *  >;
+ * }
+ * ```
  */
 model ResourceNameParameter<
   Resource extends Foundations.SimpleResource,
@@ -41,6 +53,13 @@ model ResourceNameParameter<
  * See more details on [different Azure Resource Manager resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
  * @template Properties A model containing the provider-specific properties for this resource
  * @template PropertiesOptional A boolean flag indicating whether the resource `Properties` field is marked as optional or required. Default true is optional and recommended.
+ *
+ * @example
+ * ```typespec
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>
+ * }
+ * ```
  */
 @doc("Concrete tracked resource types can be created by aliasing this type using a specific property type.")
 @armResourceInternal(Properties)
@@ -59,6 +78,13 @@ model TrackedResource<Properties extends {}, PropertiesOptional extends valueof
  * See more details on [different Azure Resource Manager resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
  * @template Properties A model containing the provider-specific properties for this resource
  * @template PropertiesOptional A boolean flag indicating whether the resource `Properties` field is marked as optional or required. Default true is optional and recommended.
+ *
+ * @example
+ * ```typespec
+ * model Employee is ProxyResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>;
+ * }
+ * ```
  */
 @doc("Concrete proxy resource types can be created by aliasing this type using a specific property type.")
 @armResourceInternal(Properties)
@@ -77,6 +103,18 @@ model ProxyResource<Properties extends {}, PropertiesOptional extends valueof bo
  * See more details on [different Azure Resource Manager resource type here.](https://azure.github.io/typespec-azure/docs/howtos/ARM/resource-type)
  * @template Properties A model containing the provider-specific properties for this resource
  * @template PropertiesOptional A boolean flag indicating whether the resource `Properties` field is marked as optional or required. Default true is optional and recommended.
+ *
+ * @example
+ * ```typespec
+ * model PetInstance is ExtensionResource<PetProperties> {
+ *  @key
+ *  @path
+ *  @segment("petInstances")
+ *  @pattern("^[a-zA-Z0-9-]{3,24}$")
+ *  @visibility(Lifecycle.Read)
+ *  name: string;
+ * }
+ * ```
  */
 @extensionResource
 @doc("Concrete extension resource types can be created by aliasing this type using a specific property type.")
@@ -290,6 +328,15 @@ model ResourceKindProperty {
 /**
  * Paged response containing resources
  * @template Resource The type of the values returned in the paged response (must be a resource)
+ *
+ * @example
+ * ```typespec
+ * op list is ArmResourceActionSync<
+ *  Resource = Employee,
+ *  Request = void,
+ *  Response = ResourceListResult<Employee>
+ * >;
+ * ```
  */
 @doc("The response of a {name} list operation.", Resource)
 @friendlyName("{name}ListResult", Resource)
@@ -396,10 +443,11 @@ model EncryptionProperty {
 /**
  * Model representing the standard `zones` envelope property for a resource.
  * Spread this model into a resource Model if the resource supports ARM `zones`.
+ *
  * @example
- * ```typescript
+ * ```typespec
  * model Foo is TrackedResource<FooProperties> {
- *   ...AvailabilityZonesProperty;
+ *  ...AvailabilityZonesProperty;
  * }
  * ```
  */

package/lib/parameters.tsp

@@ -53,12 +53,28 @@ model LocationResourceParameter {
 /**
  * The location resource for tenant-based locations.  This can be used as a parent
  * resource for resource types that are homed in a tenant-based location.
+ *
+ * @example
+ * ```typespec
+ * @parentResource(TenantLocationResource)
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>
+ * }
+ * ```
  */
 model TenantLocationResource is ArmLocationResource<"Tenant">;
 
 /**
  * The location resource for subscription-based locations.  This can be used as a parent
  * resource for resource types that are homed in a subscription-based location.
+ *
+ * @example
+ * ```typespec
+ * @parentResource(SubscriptionLocationResource)
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>;
+ * }
+ * ```
  */
 model SubscriptionLocationResource is ArmLocationResource<"Subscription">;
 
@@ -72,6 +88,14 @@ model ResourceGroupLocationResource is ArmLocationResource<"ResourceGroup">;
  * Template for ARM location resources.  Use the parameter to specify
  * the parent of the location resource.
  * @template BaseType The parent of the location, one of "Subscription", "Tenant", "ResourceGroup", or "Extension".
+ *
+ * @example
+ * ```typespec
+ * @parentResource(ArmLocationResource<"ResourceGroup">)
+ * model Employee is TrackedResource<EmployeeProperties> {
+ *  ...ResourceNameParameter<Employee>;
+ * }
+ * ```
  */
 @friendlyName("Location")
 @armVirtualResource
@@ -87,6 +111,13 @@ model ArmLocationResource<BaseType extends
 
 /**
  * The default resourceUri parameter type.
+ *
+ * @example
+ * ```typespec
+ * model Employee {
+ *  ...ResourceUriParameter;
+ * }
+ * ```
  */
 @doc("The default resourceUri parameter type.")
 model ResourceUriParameter {
@@ -101,6 +132,13 @@ model ResourceUriParameter {
  * where the resource is based.  The default is in a resource group
  * @template Resource The resource to get parameters for
  * @template BaseParameters The parameters representing the base Uri of the resource
+ *
+ * @example
+ * ```typespec
+ * op get(
+ *  ...ResourceInstanceParameters<Employee>,
+ * ): ArmResponse<EmployeeResponse> | ErrorResponse;
+ * ```
  */
 model ResourceInstanceParameters<
   Resource extends {},
@@ -146,6 +184,11 @@ alias TenantInstanceParameters<Resource extends Foundations.SimpleResource> = Re
 
 /**
  * Template used by ArmProviderAction templates.
+ *
+ * @example
+ * ```typespec
+ * op action is ArmProviderActionSync<Response = Employee, Scope = SubscriptionActionScope>;
+ * ```
  */
 @armVirtualResource
 @subscriptionResource
@@ -160,6 +203,11 @@ model SubscriptionActionScope {
 
 /**
  * Template used by ArmTenantAction templates.
+ *
+ *  @example
+ * ```typespec
+ * op action is ArmProviderActionSync<Response = Employee, Scope = TenantActionScope>;
+ * ```
  */
 @armVirtualResource
 @tenantResource

package/lib/responses.tsp

@@ -10,6 +10,11 @@ namespace Azure.ResourceManager;
 /**
  * The Azure Resource Manager synchronous OK response
  * @template ResponseBody The contents of the response body
+ *
+ * @example
+ * ```typespec
+ *  op get is ArmResourceRead<Employee, Response = ArmResponse<Employee>>;
+ * ```
  */
 @doc("Azure operation completed successfully.")
 model ArmResponse<ResponseBody> {
@@ -24,6 +29,15 @@ model ArmResponse<ResponseBody> {
  * The Azure Resource Manager 201 response for a resource
  * @template ResponseBody The contents of the response body
  * @template ExtraHeaders Additional headers in the response. Default includes Retry-After header
+ *
+ * @example
+ * ```typespec
+ * @post
+ * op post(...ResourceInstanceParameters<Employee>): ArmCreatedResponse<
+ *   Employee,
+ *   ExtraHeaders = {@header("x-ms-client-request-id") clientRequestId: string}
+ * >;
+ * ```
  */
 @doc("Azure create operation completed successfully.")
 model ArmCreatedResponse<
@@ -37,6 +51,15 @@ model ArmCreatedResponse<
 
 /**
  * The response for synchronous delete of a resource
+ *
+ * @example
+ * ```typespec
+ *  @delete
+ *  @armResourceDelete(Employee)
+ * op delete(
+ *    ...ResourceInstanceParameters<Employee>,
+ *  ): ArmDeletedResponse | ArmDeletedNoContentResponse | ErrorResponse;
+ * ```
  */
 @doc("Resource deleted successfully.")
 model ArmDeletedResponse {
@@ -46,6 +69,14 @@ model ArmDeletedResponse {
 /**
  * @dev The response for asynchronous Azure Resource Manager delete ACCEPTED
  * @template LroHeaders Optional.  Allows overriding the Lro headers returned in the response.
+ *
+ * @example
+ * ```typespec
+ * op delete is ArmResourceDeleteWithoutOkAsync<
+ *  Employee,
+ *  Response = ArmDeleteAcceptedLroResponse | ArmDeletedNoContentResponse
+ *>;
+ * ```
  */
 model ArmDeleteAcceptedLroResponse<LroHeaders extends TypeSpec.Reflection.Model = ArmLroLocationHeader &
   Azure.Core.Foundations.RetryAfterHeader>
@@ -60,6 +91,15 @@ model ArmDeleteAcceptedResponse is ArmAcceptedResponse<"Resource deletion accept
  * @dev The standard ACCEPTED response
  * @template Message The description of the response status (defaults to `Resource operation accepted`)
  * @template ExtraHeaders Additional headers in the response. Default includes Retry-After header
+ *
+ * @example
+ * ```typespec
+ * op post is ArmProviderActionSync<
+ *  Request = Employee,
+ *  Response = ArmAcceptedResponse<ExtraHeaders = ArmLroLocationHeader>,
+ *  Scope = SubscriptionActionScope
+ * >;
+ * ```
  */
 @doc(Message)
 model ArmAcceptedResponse<
@@ -74,6 +114,17 @@ model ArmAcceptedResponse<
  * @dev The standard Azure Resource Manager response for asynchronous PATCH, POST, and DELETE operations
  * @template Description The description of the response status (defaults to `Resource operation accepted`)
  * @template LroHeaders Optional.  The lro headers that appear in the Accepted response
+ *
+ * @example
+ * ```typespec
+ * @post
+ * op post(
+ *  ...ResourceInstanceParameters<Employee>,
+ * ): ArmAcceptedLroResponse<
+ *    LroHeaders = ArmLroLocationHeader<FinalResult = Employee> &
+ *    Azure.Core.Foundations.RetryAfterHeader
+ * > | ErrorResponse;
+ * ```
  */
 @doc(Description)
 model ArmAcceptedLroResponse<
@@ -134,6 +185,16 @@ model ArmOperationStatus<
  *  @template StatusMonitor The status monitor type for lro polling
  *  @template UrlValue The value type of the Azure-AsyncOperation header
  *  @template FinalResult The logical final result of the operation
+ *
+ * @example
+ * ```typespec
+ * op changeWidget is ArmResourceActionAsync<
+ *  WidgetResource,
+ *  WidgetResourceRequest,
+ *  WidgetResourceResponse,
+ *  LroHeaders = ArmAsyncOperationHeader<FinalResult = WidgetResource>
+ * >;
+ * ```
  */
 model ArmAsyncOperationHeader<
   StatusMonitor extends {} = ArmOperationStatus,
@@ -152,6 +213,19 @@ model ArmAsyncOperationHeader<
  * @template LroPollingOptions The polling options when polling the url in the location header
  * @template FinalResult The ultimate final result of the logical operation
  * @template UrlValue The value type for the location header
+ * 
+ * @example
+ * ```typespec
+ * op update is ArmResourceActionAsync<
+ *  Employee,
+ *  Employee,
+ *  OkResponse,
+ *  LroHeaders = ArmLroLocationHeader<
+ *    Azure.Core.StatusMonitorPollingOptions<ArmOperationStatus>,
+ *    Employee
+ *  >
+  >;
+ * ```
  */
 model ArmLroLocationHeader<
   LroPollingOptions extends Azure.Core.PollingOptions = Azure.Core.StatusMonitorPollingOptions<PollingModel = ArmOperationStatus>,
@@ -171,6 +245,14 @@ model ArmLroLocationHeader<
  * @template FinalResult The type of the logical result when following the location header
  * @template PollingUrlValue The value type of the link to the status monitor
  * @template FinalUrlValue The value type fo the link to the final result
+ *
+ * @example
+ * ```typespec
+ *  op delete is ArmResourceDeleteWithoutOkAsync<
+ *    Employee,
+ *    LroHeaders = ArmCombinedLroHeaders<ArmOperationStatus, Employee>
+ *  >;
+ * ```
  */
 model ArmCombinedLroHeaders<
   StatusMonitor extends {} = ArmOperationStatus,
@@ -191,12 +273,26 @@ model ArmCombinedLroHeaders<
 
 /**
  * @dev Azure Resource Manager response for a properly formed delete request, with no resource found
+ *
+ * @example
+ * ```typespec
+ * op delete is ArmResourceDeleteWithoutOkAsync<
+ *  Employee,
+ *  Response = ArmDeleteAcceptedLroResponse | ArmDeletedNoContentResponse
+ * >;
+ * ```
  */
 model ArmDeletedNoContentResponse is ArmNoContentResponse<"Resource does not exist.">;
 
 /**
  * Standard Azure Resource Manager NoContent (204) response
  * @template Message The description of the response status (defaults to `Operation completed successfully`)
+ *
+ * @example
+ * ```typespec
+ * @delete
+ * op delete(@path id:string): ArmNoContentResponse;
+ * ```
  */
 @doc(Message)
 model ArmNoContentResponse<Message extends valueof string = "Operation completed successfully."> {
@@ -206,6 +302,14 @@ model ArmNoContentResponse<Message extends valueof string = "Operation completed
 /**
  * @dev Resource update operation succeeded
  * @template Resource The resource being updated
+ *
+ * @example
+ * ```typespec
+ * @put
+ * op update(
+ *  ...ResourceInstanceParameters<Employee>,
+ * ): ArmResourceUpdatedResponse<Employee>;
+ * ```
  */
 @doc("Resource '{name}' update operation succeeded", Resource)
 model ArmResourceUpdatedResponse<Resource extends Azure.ResourceManager.Foundations.SimpleResource>
@@ -215,6 +319,17 @@ model ArmResourceUpdatedResponse<Resource extends Azure.ResourceManager.Foundati
  * @dev Resource create operation succeeded
  * @template Resource The resource being updated
  * @template LroHeaders Optional. The lro headers returned with a Created response
+ *
+ * @example
+ * ```typespec
+ * op createOrUpdate is ArmResourceCreateOrReplaceAsync<
+ *   Employee,
+ *   Response = ArmResponse<Employee> | ArmResourceCreatedResponse<
+ *     Employee,
+ *     LroHeaders = ArmLroLocationHeader<FinalResult = Employee> & Azure.Core.Foundations.RetryAfterHeader
+ *   >
+ * >;
+ * ```
  */
 @doc("Resource '{name}' create operation succeeded", Resource)
 model ArmResourceCreatedResponse<
@@ -233,6 +348,14 @@ model ArmResourceCreatedResponse<
 /**
  * @dev Resource synchronous create operation succeeded
  * @template Resource The resource being updated
+ *
+ * @example
+ * ```typespec
+ * op createOrUpdate is ArmResourceCreateOrReplaceSync<
+ *  Employee,
+ *  Response = ArmResponse<Employee> | ArmResourceCreatedSyncResponse<Employee>
+ * >;
+ * ```
  */
 @doc("Resource '{name}' create operation succeeded", Resource)
 model ArmResourceCreatedSyncResponse<Resource extends Azure.ResourceManager.Foundations.SimpleResource> {
@@ -245,6 +368,12 @@ model ArmResourceCreatedSyncResponse<Resource extends Azure.ResourceManager.Foun
 
 /**
  * @dev Resource exists response
+ *
+ * @example
+ * ```typespec
+ * @head
+ * op head(...ResourceInstanceParameters<Employee>): ArmResourceExistsResponse;
+ * ```
  */
 @doc("The Azure resource exists")
 model ArmResourceExistsResponse {
@@ -253,6 +382,10 @@ model ArmResourceExistsResponse {
 
 /**
  * @dev Resource is not found response
+ * ```typespec
+ * @head
+ * op head(...ResourceInstanceParameters<Employee>): ArmResponse<Employee>  | ArmResourceNotFoundResponse;
+ * ```
  */
 @doc("The Azure resource is not found")
 model ArmResourceNotFoundResponse {

package/package.json

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