Enhance documentation for @typeChangedFrom and @returnTypeChangedFrom decorators

[Copilot]

The versioning decorators @typeChangedFrom and @returnTypeChangedFrom had minimal JSDoc comments ("Identifies when the target type changed"), insufficient for LLMs and developers to understand their behavior and correct usage.

Changes

• Enhanced JSDoc comments in packages/versioning/lib/decorators.tsp:

  • Clarified that decorators declare type changes starting at a specific version while maintaining consistency with earlier versions
  • Explained version semantics: old type applies before specified version, new type from version onwards
  • Added parameter descriptions detailing when changes take effect
  • Included practical examples showing type evolution (e.g., string → int32)

• Regenerated reference docs at website/src/content/docs/docs/libraries/versioning/reference/decorators.md

Example

Before, documentation simply stated "The version that the target type changed in." Now:

model Foo {
  // In v1: id is a string
  // In v2+: id is an int32
  @typeChangedFrom(Versions.v2, string)
  id: int32;
}

With clear explanation that the property uses string before v2 and int32 from v2 onwards.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[doc] The description of the decorators for versioning lacks the details on how to use it.</issue_title>
<issue_description>It would cause AI to provide the incorrect answer as it does not understand those decorators.

E.g. https://typespec.io/docs/libraries/versioning/reference/decorators/#@TypeSpec.Versioning.typeChangedFrom

Suggestion for:
@typeChangedFrom : declare that the type of a declaration has changed starting at a given version, while keeping earlier versions consistent with the previous type.

version: One of service’s versions indicating when the change takes effect.
previousType: The old type used before the specified version.</issue_description>

<agent_instructions>Please update the jsdoc comments for the versioning decorators to indicate what they do, then regenerate the reference docs for them.

@typeChangedFrom( , ) indicates that the type of the decorated parameter or property was in versions before .

@renamedFrom(, ) indicates that the decorated type used the name in versions before

@returnTypeChangedFrom( , ) indicates that the return type of the decorated operation was in versions before .

@madeOptional( ) indicates that the decorated parameter or property was required in versions before

@added( < Version>) indicates that the decorated type does not exist in versions before . (Unless the type is decorated with @added referencing some earlier version)

@removed() indicates that the decorated does not appear in or any version afterwards. (Unless the type is decorated with @added referencing a later version)</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [doc] The description of the decorators for versioning lacks the details on how to use it. #9344

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.