obsolete/deprecation/g (#773)

Author: delvedor

compiler/model/utils.ts

@@ -491,16 +491,15 @@ export function modelProperty (declaration: PropertySignature | PropertyDeclarat
 }
 
 /**
- * Pulls @obsolete and @obsolete_description from types and properties
+ * Pulls @deprecated from types and properties
  */
-function setObsolete (type: model.BaseType | model.Property | model.EnumMember, tags: Record<string, string>): void {
-  const obsolete = tags.obsolete
-  const description = tags.obsolete_description
-  if (obsolete !== undefined) {
-    type.deprecation = { version: obsolete, description: description }
+function setDeprecated (type: model.BaseType | model.Property | model.EnumMember, tags: Record<string, string>, jsDocs: JSDoc[]): void {
+  if (tags.deprecated !== undefined) {
+    const [version, ...description] = tags.deprecated.split(' ')
+    assert(jsDocs, semver.valid(version), 'Invalid semver value')
+    type.deprecation = { version, description: description.join(' ') }
   }
-  delete tags.obsolete
-  delete tags.obsolete_description
+  delete tags.deprecated
 }
 
 /**
@@ -515,7 +514,7 @@ function setTags<TType extends model.BaseType | model.Property | model.EnumMembe
 ): void {
   if (Object.keys(tags).length === 0) return
 
-  setObsolete(type, tags)
+  setDeprecated(type, tags, jsDocs)
   const badTags = Object.keys(tags).filter(tag => !validTags.includes(tag))
   assert(
     jsDocs,

docs/modeling-guide.md

@@ -516,3 +516,27 @@ export interface Request extends RequestBase {
  ...
 }
 ```
+
+#### `@deprecated`
+
+Use if an endpoint or property is deprecated, you should add the version as well.
+
+```ts
+class Foo {
+  bar: string
+  /** @deprecated 7.0.0 */
+  baz?: string
+  faz: string
+}
+```
+
+You can also add an optional description:
+
+```ts
+class Foo {
+  bar: string
+  /** @deprecated 7.0.0 'baz' has been deprecated, use 'bar' instead */
+  baz?: string
+  faz: string
+}
+```

output/schema/schema.json

@@ -38,7 +38,7 @@ export class Response<TDocument> {
     _routing?: string
     _seq_no?: SequenceNumber
     _source?: TDocument
-    /** @obsolete 7.0.0 */
+    /** @deprecated 7.0.0 */
     _type?: Type
     _version?: VersionNumber
   }

specification/_global/get/GetResponse.ts

@@ -28,7 +28,7 @@ import { Time } from '@_types/Time'
  */
 export interface Request extends RequestBase {
   path_parts: {
-    /** @obsolete 7.0.0 */
+    /** @deprecated 7.0.0 */
     scroll_id?: Id
   }
   query_parameters: {
@@ -38,7 +38,7 @@ export interface Request extends RequestBase {
      * @server_default 1d
      */
     scroll?: Time
-    /** @obsolete 7.0.0 */
+    /** @deprecated 7.0.0 */
     scroll_id?: ScrollId
     /**
      * If true, the API response’s hit.total property is returned as an integer. If false, the API response’s hit.total property is returned as an object.

specification/_global/scroll/ScrollRequest.ts

@@ -100,7 +100,7 @@ import {
 export class QueryContainer {
   bool?: BoolQuery
   boosting?: BoostingQuery
-  /** @obsolete 7.3.0 */
+  /** @deprecated 7.3.0 */
   common?: SingleKeyDictionary<Field, CommonTermsQuery>
   /** @since 7.13.0 */
   combined_fields?: CombinedFieldsQuery
@@ -154,8 +154,7 @@ export class QueryContainer {
   wildcard?: SingleKeyDictionary<Field, WildcardQuery>
 
   /**
-   * @obsolete 7.0.0
-   * @obsolete_description https://www.elastic.co/guide/en/elasticsearch/reference/7.x/removal-of-types.html
+   * @deprecated 7.0.0 https://www.elastic.co/guide/en/elasticsearch/reference/7.x/removal-of-types.html
    */
   type?: TypeQuery
 }

specification/_types/query_dsl/abstractions.ts

@@ -135,7 +135,7 @@ export class MatchQuery extends QueryBase {
   analyzer?: string
   /** @server_default true */
   auto_generate_synonyms_phrase_query?: boolean
-  /** @obsolete 7.3.0 */
+  /** @deprecated 7.3.0 */
   cutoff_frequency?: double
   fuzziness?: Fuzziness
   fuzzy_rewrite?: MultiTermQueryRewrite
@@ -192,7 +192,7 @@ export class MultiMatchQuery extends QueryBase {
   analyzer?: string
   /** @server_default true */
   auto_generate_synonyms_phrase_query?: boolean
-  /** @obsolete 7.3.0 */
+  /** @deprecated 7.3.0 */
   cutoff_frequency?: double
   fields?: Fields
   fuzziness?: Fuzziness

specification/_types/query_dsl/fulltext.ts

@@ -51,7 +51,7 @@ export class BoundingBox {
 export class GeoBoundingBoxQuery
   extends QueryBase
   implements AdditionalProperty<Field, BoundingBox> {
-  /** @obsolete 7.14.0 */
+  /** @deprecated 7.14.0 */
   type?: GeoExecution
   /** @server_default 'strict' */
   validation_method?: GeoValidationMethod
@@ -77,7 +77,7 @@ export class GeoPolygonPoints {
   points: GeoLocation[]
 }
 
-/** @obsolete 7.12.0 Use geo-shape instead. */
+/** @deprecated 7.12.0 Use geo-shape instead. */
 export class GeoPolygonQuery
   extends QueryBase
   implements AdditionalProperty<Field, GeoPolygonPoints> {

specification/_types/query_dsl/geo.ts

@@ -47,8 +47,7 @@ export interface Request extends RequestBase {
      */
     allow_no_match?: boolean
     /**
-     * @obsolete 7.10.0
-     * @obsolete_description Use `allow_no_match` instead.
+     * @deprecated 7.10.0 Use `allow_no_match` instead.
      */
     allow_no_jobs?: boolean
     /**

specification/ml/close_job/MlCloseJobRequest.ts

@@ -29,7 +29,7 @@ import { OperationContainer } from '@global/bulk/types'
 export interface Request<TSource> extends RequestBase {
   path_parts: {
     /**
-     * @obsolete 7.0.0
+     * @deprecated 7.0.0
      */
     type?: string
   }