Add @availability tag to EnumMembers

Author: sethmlarson

compiler/src/model/metamodel.ts

@@ -334,6 +334,7 @@ export class EnumMember {
   description?: string
   deprecation?: Deprecation
   since?: string
+  availability?: Availabilities
 }
 
 /**

compiler/src/model/utils.ts

@@ -850,7 +850,7 @@ function hoistEnumMemberAnnotations (member: model.EnumMember, jsDocs: JSDoc[]):
   // We want to enforce a single jsDoc block.
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
-  const validTags = ['obsolete', 'obsolete_description', 'codegen_name', 'since', 'aliases']
+  const validTags = ['obsolete', 'obsolete_description', 'codegen_name', 'availability', 'aliases']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -862,9 +862,26 @@ function hoistEnumMemberAnnotations (member: model.EnumMember, jsDocs: JSDoc[]):
       member.codegenName = value
     } else if (tag === 'aliases') {
       member.aliases = parseCommaSeparated(value)
-    } else if (tag === 'since') {
-      assert(jsDocs, semver.valid(value), `${member.name}'s @since is not valid semver: ${value}`)
-      member.since = value
+    } else if (tag === 'availability') {
+      // The @availability jsTag is different than most because it allows
+      // multiple values within the same docstring, hence needing to parse
+      // the values again in order to preserve multiple values.
+      const jsDocsMulti = parseJsDocTagsAllowDuplicates(jsDocs)
+      const availabilities = parseAvailabilityTags(jsDocs, jsDocsMulti.availability)
+
+      // The absence of an 'availability' field on a property implies that
+      // the property is available in all flavors.
+      member.availability = {}
+      for (const [availabilityName, availabilityValue] of Object.entries(availabilities)) {
+        member.availability[availabilityName] = availabilityValue
+
+        // Backfilling deprecated fields on a property.
+        if (availabilityName === 'stack') {
+          if (availabilityValue.since !== undefined) {
+            member.since = availabilityValue.since
+          }
+        }
+      }
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on enum member ${member.name}`)
     }

output/schema/schema.json

@@ -20,7 +20,10 @@
 export enum GridType {
   grid,
   point,
-  /** @since 7.16.0 */
+  /**
+   * @availability stack since=7.16.0
+   * @availability serverless
+   */
   centroid
 }
 

specification/_global/search_mvt/_types/GridType.ts

@@ -223,7 +223,8 @@ export class ShardStats {
 }
 
 /**
- * @since 8.1.0
+ * @availability stack since=8.1.0
+ * @availability serverless
  */
 export enum IndexMetadataState {
   open,

specification/indices/stats/types.ts

@@ -75,10 +75,19 @@ export enum SnapshotSort {
   duration,
   name,
   index_count,
-  /** @since 7.16.0 */
+  /**
+   * @availability stack since=7.16.0
+   * @availability serverless
+   */
   repository,
-  /** @since 7.16.0 */
+  /**
+   * @availability stack since=7.16.0
+   * @availability serverless
+   */
   shard_count,
-  /** @since 7.16.0 */
+  /**
+   * @availability stack since=7.16.0
+   * @availability serverless
+   */
   failed_shard_count
 }

specification/snapshot/_types/SnapshotInfo.ts

@@ -334,6 +334,7 @@ export class EnumMember {
   description?: string
   deprecation?: Deprecation
   since?: string
+  availability?: Availabilities
 }
 
 /**