Versioning of documentation updates to avoid unintended updates to data-plane files

[jpalvarezl]

What is this about

While working on the Azure OpenAI TypeSpec definition, sometimes we need to update the documentation of fields and models. Doing so, retroactively updates the documentation in the OpenAPI v2 generated files in the associated data-plane subfolder.

To keep old spec versions' documentation in the same state as when it was written, it would be useful to be able to specify with a decorator or in a different way, up to which version this documentation is still valid.

Example

Let's say for instance, we have a model that looks like this:

/**
 * My model documentation
 */ 
model Foo {
  /** Bar field */
  bar: string
// ...
}

Which gets updated to:

/**
 * My model documentation
 */ 
model Foo {
  /** Bar field. This field is facing deprecation and won't be available as of January 2025. */
  bar: string;

  /** Baz field. Replacement of Bar field. */
  baz: BazModel;
// ...
}

In this example, we would have to have a 2nd update to the documentation of baz removing the "Replacement of Bar field." bit of the doc. But being able to update docs like this, would enable us to provide better guidance to our customers on the usage of our SDKs.

Whenever we reach the point when the field needs to be removed, we will use the appropriate decorator @removed(ServiceVersions.some_version) (or @TypeChangedFrom) but it would be good be able to notify users about the deprecation ahead of time by updating the documentation without affecting our documentation history in the data-plane folder.

Additionally, these documentation changes often times come from OpenAI as an upstream dependency update. A concrete recent example of this can be found for the maxToken field affected by this PR.

Proposal

Making @doc accept a version parameter, or introducing a new decorator into the versioning decorator suite along the lines of @docLastUpdated(ServiceVersions.some_version) could signal emitters, particularly in the case of emitting OpenAPI files in the data-plane folder, to ignore the documentation value update up to the service version provided in the parameter of the decorator.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.