From ed25d55ac07953089e35d7c30850613a64e72492 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 19 Apr 2024 12:24:11 -0700 Subject: [PATCH 1/2] update docs to reference union instead of unions --- docs/howtos/ARM/resource-type.md | 28 ++++++-- .../Azure Core/long-running-operations.md | 64 ++++++++++--------- .../typespec-azure-core/lib/decorators.tsp | 1 + 3 files changed, 59 insertions(+), 34 deletions(-) diff --git a/docs/howtos/ARM/resource-type.md b/docs/howtos/ARM/resource-type.md index d80ee2a22c..05c5228a21 100644 --- a/docs/howtos/ARM/resource-type.md +++ b/docs/howtos/ARM/resource-type.md @@ -225,11 +225,29 @@ model EmployeeResource is TrackedResource { name: string; } -enum EmployeeProvisioningState { - Creating, - GeneratingId, - ...ResourceProvisioningState, - Deleting, +union EmployeeProvisioningState { + string, + + /** The resource create request has been accepted */ + Accepted: "Accepted", + + /** The resource is being provisioned */ + Provisioning: "Provisioning", + + /** The resource is updating */ + Updating: "Updating", + + /** Resource has been created. */ + Succeeded: "Succeeded", + + /** Resource creation failed. */ + Failed: "Failed", + + /** Resource creation was canceled. */ + Canceled: "Canceled", + + /** The resource is being deleted */ + Deleting: "Deleting", } @minValue(50) diff --git a/docs/howtos/Azure Core/long-running-operations.md b/docs/howtos/Azure Core/long-running-operations.md index a8a557b47e..ef00a55de4 100644 --- a/docs/howtos/Azure Core/long-running-operations.md +++ b/docs/howtos/Azure Core/long-running-operations.md @@ -110,12 +110,12 @@ A StatusMonitor provides information that drives client polling until an operati | Decorator | Value | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@lroStatus` | A decorator marking the field of the StatusMonitor that contains status information. This field should use an `enum` type to specify terminal status values. | +| `@lroStatus` | A decorator marking the field of the StatusMonitor that contains status information. This field should use a `union` type to specify terminal status values. | | `@lroResult` | A decorator marking the property of the Status monitor that contains the result of the operation, when the operation completes successfully. By default, any field named 'result' in a StatusMonitor is assumed to contain the result of a successful operation. | | `@lroErrorResult` | A decorator marking the property of the Status monitor that contains errors when the operation is unsuccessful. By default, any field named 'error' in a StatusMonitor is assumed to contain the result of a successful operation. | -| `@lroSucceeded` | If a status monitor uses a value other than `Succeeded` to indicate operation termination with success, then the enum value corresponding to successful completion should be decorated with this decorator. | -| `@lroCanceled` | If a status monitor uses a value other than `Canceled` to indicate that the operation was cancelled, then the enum value corresponding to cancellation should be decorated with this decorator. | -| `@lroFailed` | If a status monitor uses a value other than `Failed` to indicate operation termination with failure, then the enum value corresponding to operation failure should be decorated with this decorator. | +| `@lroSucceeded` | If a status monitor uses a value other than `Succeeded` to indicate operation termination with success, then the variant corresponding to successful completion should be decorated with this decorator. | +| `@lroCanceled` | If a status monitor uses a value other than `Canceled` to indicate that the operation was cancelled, then the variant corresponding to cancellation should be decorated with this decorator. | +| `@lroFailed` | If a status monitor uses a value other than `Failed` to indicate operation termination with failure, then the variant corresponding to operation failure should be decorated with this decorator. | | `@pollingOperationParameter` | Indicates which request parameters or response properties of an operation can be used to call the operation that retrieves lro status (Status Monitor). Each application of the decorator may reference or name the corresponding parameter in the `getStatus` operation. | ### Examples of common (non-standard) Lro Patterns @@ -133,17 +133,19 @@ In this example, the Status Monitor terminal properties for "Succeeded", "Failed ```tsp @lroStatus -enum OperationStatus { - Running, +union OperationStatus { + Running: "Running", @lroSucceeded - Completed, + Completed: "Completed", @lroCanceled - Aborted, + Aborted: "Aborted", @lroFailed - Faulted, + Faulted: "Faulted", + + string, } model StatusMonitor { @@ -249,11 +251,12 @@ In this example, the operation returns a `location` header with a link to the St ```tsp @lroStatus -enum OperationStatus { - Running, - Succeeded, - Canceled, - Failed, +union OperationStatus { + Running: "Running", + Succeeded: "Succeeded", + Canceled: "Canceled", + Failed: "Failed", + string, } model StatusMonitor { @@ -316,11 +319,12 @@ In this example, the operation returns a `Azure-AsyncOperation` header with a li ```tsp @lroStatus -enum OperationStatus { - Running, - Succeeded, - Canceled, - Failed, +union OperationStatus { + Running: "Running", + Succeeded: "Succeeded", + Canceled: "Canceled", + Failed: "Failed", + string, } model StatusMonitor { @@ -384,11 +388,12 @@ In this example, the operation returns a link to the Status Monitor (in `Azure-A ```tsp @lroStatus -enum OperationStatus { - Running, - Succeeded, - Canceled, - Failed, +union OperationStatus { + Running: "Running", + Succeeded: "Succeeded", + Canceled: "Canceled", + Failed: "Failed", + string, } model StatusMonitor { @@ -464,11 +469,12 @@ In this example, the operation does not return a link, instead, the request para ```tsp @lroStatus -enum OperationStatus { - Running, - Succeeded, - Canceled, - Failed, +union OperationStatus { + Running: "Running", + Succeeded: "Succeeded", + Canceled: "Canceled", + Failed: "Failed", + string, } model StatusMonitor { diff --git a/packages/typespec-azure-core/lib/decorators.tsp b/packages/typespec-azure-core/lib/decorators.tsp index 8e8ed1bd89..3832078b0e 100644 --- a/packages/typespec-azure-core/lib/decorators.tsp +++ b/packages/typespec-azure-core/lib/decorators.tsp @@ -6,6 +6,7 @@ namespace Azure { * Marks an Enum as being fixed since enums in Azure are * assumed to be extensible. */ + #deprecated "Enums are now fixed by default. This decorator is no longer necessary." extern dec fixed(target: Enum); /** From eb7cbdfcac2bd79a4bcc4199972f538824d81f0e Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Fri, 19 Apr 2024 12:30:55 -0700 Subject: [PATCH 2/2] Update decorators.tsp --- packages/typespec-azure-core/lib/decorators.tsp | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/typespec-azure-core/lib/decorators.tsp b/packages/typespec-azure-core/lib/decorators.tsp index 3832078b0e..8e8ed1bd89 100644 --- a/packages/typespec-azure-core/lib/decorators.tsp +++ b/packages/typespec-azure-core/lib/decorators.tsp @@ -6,7 +6,6 @@ namespace Azure { * Marks an Enum as being fixed since enums in Azure are * assumed to be extensible. */ - #deprecated "Enums are now fixed by default. This decorator is no longer necessary." extern dec fixed(target: Enum); /**