From e63c30094b6ca69b4e2249ea91714bf2c8251d62 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 2 Feb 2026 23:56:01 +0000 Subject: [PATCH 1/3] Initial plan From 9a61b6c28379d16b301b8149ebf2b151ffac6f11 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 3 Feb 2026 00:05:29 +0000 Subject: [PATCH 2/3] Improve JSDoc for versioning decorators @typeChangedFrom and @returnTypeChangedFrom Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- packages/versioning/README.md | 50 +++++++++++++++---- .../generated-defs/TypeSpec.Versioning.ts | 40 ++++++++++++--- packages/versioning/lib/decorators.tsp | 46 ++++++++++++++--- .../versioning/reference/decorators.md | 50 +++++++++++++++---- 4 files changed, 154 insertions(+), 32 deletions(-) diff --git a/packages/versioning/README.md b/packages/versioning/README.md index 2f1bdad5203..1b8adf74f7e 100644 --- a/packages/versioning/README.md +++ b/packages/versioning/README.md @@ -214,7 +214,12 @@ op newName(): void; #### `@returnTypeChangedFrom` -Identifies when the target type changed. +Declares that the return type of an operation has changed starting at a given version, +while keeping earlier versions consistent with the previous return type. + +This decorator is used to track return type changes across API versions. When applied, +the operation will return `oldType` in versions before the specified `version`, +and the current return type definition in the specified version and later. ```typespec @TypeSpec.Versioning.returnTypeChangedFrom(version: EnumMember, oldType: unknown) @@ -226,14 +231,28 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | ------------ | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| version | `EnumMember` | The version when the return type change takes effect. The new return type applies
from this version onwards, while the old return type applies to earlier versions. | +| oldType | `unknown` | The previous return type used before the specified version. | + +##### Examples + +```tsp +// In v1: returns a string +// In v2+: returns an int32 +@returnTypeChangedFrom(Versions.v2, string) +op getUserId(): int32; +``` #### `@typeChangedFrom` -Identifies when the target type changed. +Declares that the type of a model property has changed starting at a given version, +while keeping earlier versions consistent with the previous type. + +This decorator is used to track type changes across API versions. When applied, +the property will use `oldType` in versions before the specified `version`, +and the current type definition in the specified version and later. ```typespec @TypeSpec.Versioning.typeChangedFrom(version: EnumMember, oldType: unknown) @@ -245,10 +264,21 @@ Identifies when the target type changed. ##### Parameters -| Name | Type | Description | -| ------- | ------------ | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| version | `EnumMember` | The version when the type change takes effect. The new type applies
from this version onwards, while the old type applies to earlier versions. | +| oldType | `unknown` | The previous type used before the specified version. | + +##### Examples + +```tsp +model Foo { + // In v1: id is a string + // In v2+: id is an int32 + @typeChangedFrom(Versions.v2, string) + id: int32; +} +``` #### `@useDependency` diff --git a/packages/versioning/generated-defs/TypeSpec.Versioning.ts b/packages/versioning/generated-defs/TypeSpec.Versioning.ts index 8e8668c1c45..b52ff9d3df0 100644 --- a/packages/versioning/generated-defs/TypeSpec.Versioning.ts +++ b/packages/versioning/generated-defs/TypeSpec.Versioning.ts @@ -202,10 +202,25 @@ export type MadeRequiredDecorator = ( ) => DecoratorValidatorCallbacks | void; /** - * Identifies when the target type changed. + * Declares that the type of a model property has changed starting at a given version, + * while keeping earlier versions consistent with the previous type. * - * @param version The version that the target type changed in. - * @param oldType The previous type of the target. + * This decorator is used to track type changes across API versions. When applied, + * the property will use `oldType` in versions before the specified `version`, + * and the current type definition in the specified version and later. + * + * @param version The version when the type change takes effect. The new type applies + * from this version onwards, while the old type applies to earlier versions. + * @param oldType The previous type used before the specified version. + * @example + * ```tsp + * model Foo { + * // In v1: id is a string + * // In v2+: id is an int32 + * @typeChangedFrom(Versions.v2, string) + * id: int32; + * } + * ``` */ export type TypeChangedFromDecorator = ( context: DecoratorContext, @@ -215,10 +230,23 @@ export type TypeChangedFromDecorator = ( ) => DecoratorValidatorCallbacks | void; /** - * Identifies when the target type changed. + * Declares that the return type of an operation has changed starting at a given version, + * while keeping earlier versions consistent with the previous return type. + * + * This decorator is used to track return type changes across API versions. When applied, + * the operation will return `oldType` in versions before the specified `version`, + * and the current return type definition in the specified version and later. * - * @param version The version that the target type changed in. - * @param oldType The previous type of the target. + * @param version The version when the return type change takes effect. The new return type applies + * from this version onwards, while the old return type applies to earlier versions. + * @param oldType The previous return type used before the specified version. + * @example + * ```tsp + * // In v1: returns a string + * // In v2+: returns an int32 + * @returnTypeChangedFrom(Versions.v2, string) + * op getUserId(): int32; + * ``` */ export type ReturnTypeChangedFromDecorator = ( context: DecoratorContext, diff --git a/packages/versioning/lib/decorators.tsp b/packages/versioning/lib/decorators.tsp index fe423e85391..8422f3327ea 100644 --- a/packages/versioning/lib/decorators.tsp +++ b/packages/versioning/lib/decorators.tsp @@ -178,15 +178,49 @@ extern dec madeOptional(target: ModelProperty, version: EnumMember); extern dec madeRequired(target: ModelProperty, version: EnumMember); /** - * Identifies when the target type changed. - * @param version The version that the target type changed in. - * @param oldType The previous type of the target. + * Declares that the type of a model property has changed starting at a given version, + * while keeping earlier versions consistent with the previous type. + * + * This decorator is used to track type changes across API versions. When applied, + * the property will use `oldType` in versions before the specified `version`, + * and the current type definition in the specified version and later. + * + * @param version The version when the type change takes effect. The new type applies + * from this version onwards, while the old type applies to earlier versions. + * @param oldType The previous type used before the specified version. + * + * @example + * + * ```tsp + * model Foo { + * // In v1: id is a string + * // In v2+: id is an int32 + * @typeChangedFrom(Versions.v2, string) + * id: int32; + * } + * ``` */ extern dec typeChangedFrom(target: ModelProperty, version: EnumMember, oldType: unknown); /** - * Identifies when the target type changed. - * @param version The version that the target type changed in. - * @param oldType The previous type of the target. + * Declares that the return type of an operation has changed starting at a given version, + * while keeping earlier versions consistent with the previous return type. + * + * This decorator is used to track return type changes across API versions. When applied, + * the operation will return `oldType` in versions before the specified `version`, + * and the current return type definition in the specified version and later. + * + * @param version The version when the return type change takes effect. The new return type applies + * from this version onwards, while the old return type applies to earlier versions. + * @param oldType The previous return type used before the specified version. + * + * @example + * + * ```tsp + * // In v1: returns a string + * // In v2+: returns an int32 + * @returnTypeChangedFrom(Versions.v2, string) + * op getUserId(): int32; + * ``` */ extern dec returnTypeChangedFrom(target: Operation, version: EnumMember, oldType: unknown); diff --git a/website/src/content/docs/docs/libraries/versioning/reference/decorators.md b/website/src/content/docs/docs/libraries/versioning/reference/decorators.md index fd2cd1d88c9..e8baec6aa57 100644 --- a/website/src/content/docs/docs/libraries/versioning/reference/decorators.md +++ b/website/src/content/docs/docs/libraries/versioning/reference/decorators.md @@ -164,7 +164,12 @@ op newName(): void; ### `@returnTypeChangedFrom` {#@TypeSpec.Versioning.returnTypeChangedFrom} -Identifies when the target type changed. +Declares that the return type of an operation has changed starting at a given version, +while keeping earlier versions consistent with the previous return type. + +This decorator is used to track return type changes across API versions. When applied, +the operation will return `oldType` in versions before the specified `version`, +and the current return type definition in the specified version and later. ```typespec @TypeSpec.Versioning.returnTypeChangedFrom(version: EnumMember, oldType: unknown) @@ -176,14 +181,28 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | ------------ | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| version | `EnumMember` | The version when the return type change takes effect. The new return type applies
from this version onwards, while the old return type applies to earlier versions. | +| oldType | `unknown` | The previous return type used before the specified version. | + +#### Examples + +```tsp +// In v1: returns a string +// In v2+: returns an int32 +@returnTypeChangedFrom(Versions.v2, string) +op getUserId(): int32; +``` ### `@typeChangedFrom` {#@TypeSpec.Versioning.typeChangedFrom} -Identifies when the target type changed. +Declares that the type of a model property has changed starting at a given version, +while keeping earlier versions consistent with the previous type. + +This decorator is used to track type changes across API versions. When applied, +the property will use `oldType` in versions before the specified `version`, +and the current type definition in the specified version and later. ```typespec @TypeSpec.Versioning.typeChangedFrom(version: EnumMember, oldType: unknown) @@ -195,10 +214,21 @@ Identifies when the target type changed. #### Parameters -| Name | Type | Description | -| ------- | ------------ | -------------------------------------------- | -| version | `EnumMember` | The version that the target type changed in. | -| oldType | `unknown` | The previous type of the target. | +| Name | Type | Description | +| ------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| version | `EnumMember` | The version when the type change takes effect. The new type applies
from this version onwards, while the old type applies to earlier versions. | +| oldType | `unknown` | The previous type used before the specified version. | + +#### Examples + +```tsp +model Foo { + // In v1: id is a string + // In v2+: id is an int32 + @typeChangedFrom(Versions.v2, string) + id: int32; +} +``` ### `@useDependency` {#@TypeSpec.Versioning.useDependency} From d865fc9b0a77269ffb0e2c6e56d02f15a1a5f0c1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 5 Feb 2026 20:09:21 +0000 Subject: [PATCH 3/3] Add changeset for versioning decorator documentation improvements Co-authored-by: markcowl <1054056+markcowl@users.noreply.github.com> --- ...t-update-jsdoc-versioning-decorators-2026-1-5-20-9-3.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .chronus/changes/copilot-update-jsdoc-versioning-decorators-2026-1-5-20-9-3.md diff --git a/.chronus/changes/copilot-update-jsdoc-versioning-decorators-2026-1-5-20-9-3.md b/.chronus/changes/copilot-update-jsdoc-versioning-decorators-2026-1-5-20-9-3.md new file mode 100644 index 00000000000..5ffc8486ff8 --- /dev/null +++ b/.chronus/changes/copilot-update-jsdoc-versioning-decorators-2026-1-5-20-9-3.md @@ -0,0 +1,7 @@ +--- +changeKind: internal +packages: + - "@typespec/versioning" +--- + +Improve JSDoc documentation for @typeChangedFrom and @returnTypeChangedFrom decorators \ No newline at end of file