Add examples to the Azure.ResourceManager documentation

.chronus/changes/add-examples-data-types-arm-2025-3-22-17-5-4.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+---
+
+Added examples to the Azure.ResourceManager documentation

packages/typespec-azure-resource-manager/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 {

packages/typespec-azure-resource-manager/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. */

packages/typespec-azure-resource-manager/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;
  * }
  * ```
  */

packages/typespec-azure-resource-manager/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