Configure UpdateForV10 tag with eslint-plugin-jsdoc

We sometimes want to make breaking changes but have to wait until the next
major version. To not forget about those, this commit introduces an
UpdateForV10 JSDoc tag that can be used in any commment. There are a few
benefits of using JSDoc instead of a simple TODO comment:

 * With the allowlist of tags in our eslint config, we can't make typos
 * We enforce a proper description to explain why the breaking change needs to
   be made

Note that this tag has the same name as the Elasticsearch UpdateForV10 annotation, as
we'll migrate to Elasticsearch in the future.

Author: pquentin

docs/modeling-guide.md

@@ -785,3 +785,12 @@ class Foo {
 #### `@stability` and `@visibility`
 
 These annotations have been removed, use `@availability` instead.
+
+#### `@UpdateForV10`
+
+We sometimes want to make breaking changes but have to wait until the next major version.
+To not forget about those change, you can use the UpdateForV10 JSDoc tag in any commment.
+There are a few benefits of using JSDoc instead of a simple TODO comment:
+
+ * With the allowlist of tags in our eslint config, we can't make typos
+ * We enforce a proper description to explain why the breaking change needs to be made

specification/_global/index/IndexRequest.ts

@@ -146,12 +146,14 @@ import { Duration } from '@_types/Time'
  *     "id": "elkbee"
  *   }
  * }
- *
+ * ```
+ * 
  * In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
  * If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
  *
  * A nice side effect is that there is no need to maintain strict ordering of async indexing operations run as a result of changes to a source database, as long as version numbers from the source database are used.
  * Even the simple case of updating the Elasticsearch index using data from a database is simplified if external versioning is used, as only the latest version will be used if the index operations arrive out of order.
+ * 
  * @rest_spec_name index
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=public

specification/_global/search_template/SearchTemplateRequest.ts

@@ -122,7 +122,8 @@ export interface Request extends RequestBase {
      */
     scroll?: Duration
     /**
-     * The type of the search operation. */
+     * The type of the search operation.
+     */
     search_type?: SearchType
     /**
      * If `true`, `hits.total` is rendered as an integer in the response.

specification/_global/update_by_query/UpdateByQueryResponse.ts

@@ -32,7 +32,8 @@ export class Response {
      * If this is non-empty then the request ended because of those failures.
      * Update by query is implemented using batches.
      * Any failure causes the entire process to end, but all failures in the current batch are collected into the array.
-     * You can use the `conflicts` option to prevent reindex from ending when version conflicts occur. */
+     * You can use the `conflicts` option to prevent reindex from ending when version conflicts occur.
+     */
     failures?: BulkIndexByScrollFailure[]
     /** The number of documents that were ignored because the script used for the update by query returned a noop value for `ctx.op`. */
     noops?: long
@@ -43,7 +44,8 @@ export class Response {
     /**
      * The number of retries attempted by update by query.
      * `bulk` is the number of bulk actions retried.
-     * `search` is the number of search actions retried. */
+     * `search` is the number of search actions retried.
+     */
     retries?: Retries
     task?: TaskId
     /** If true, some requests timed out during the update by query. */
@@ -60,8 +62,10 @@ export class Response {
     /** The number of milliseconds the request slept to conform to `requests_per_second`. */
     throttled_millis?: DurationValue<UnitMillis>
     throttled_until?: Duration
-    /** This field should always be equal to zero in an _update_by_query response.
-     * It only has meaning when using the task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be run again in order to conform to `requests_per_second`. */
+    /**
+     * This field should always be equal to zero in an _update_by_query response.
+     * It only has meaning when using the task API, where it indicates the next time (in milliseconds since epoch) a throttled request will be run again in order to conform to `requests_per_second`.
+     */
     throttled_until_millis?: DurationValue<UnitMillis>
   }
 }

specification/_spec_utils/UserDefinedValue.ts

@@ -17,6 +17,8 @@
  * under the License.
  */
 
-/** Rather then documenting `object` this specifies places in the response that depend on the mapping and or request
- * e.g the result of a script can be anything from value types to objects  */
+/**
+ * Rather then documenting `object` this specifies places in the response that depend on the mapping and or request
+ * e.g the result of a script can be anything from value types to objects
+ */
 export class UserDefinedValue {}

specification/_types/Knn.ts

@@ -43,7 +43,8 @@ export interface KnnSearch {
   k?: integer
   /** The number of nearest neighbor candidates to consider per shard */
   num_candidates?: integer
-  /** The percentage of vectors to explore per shard while doing knn search with bbq_disk
+  /**
+   * The percentage of vectors to explore per shard while doing knn search with bbq_disk
    * @availability stack since=9.2.0
    * @availability serverless
    */
@@ -59,7 +60,8 @@ export interface KnnSearch {
    * @doc_id knn-inner-hits
    */
   inner_hits?: InnerHits
-  /** Apply oversampling and rescoring to quantized vectors
+  /**
+   * Apply oversampling and rescoring to quantized vectors
    * @availability stack since=8.18.0
    * @availability serverless
    */
@@ -78,7 +80,8 @@ export interface KnnQuery extends QueryBase {
   query_vector_builder?: QueryVectorBuilder
   /** The number of nearest neighbor candidates to consider per shard */
   num_candidates?: integer
-  /** The percentage of vectors to explore per shard while doing knn search with bbq_disk
+  /**
+   * The percentage of vectors to explore per shard while doing knn search with bbq_disk
    * @availability stack since=9.2.0
    * @availability serverless
    */
@@ -89,7 +92,8 @@ export interface KnnQuery extends QueryBase {
   filter?: QueryContainer | QueryContainer[]
   /** The minimum similarity for a vector to be considered a match */
   similarity?: float
-  /** Apply oversampling and rescoring to quantized vectors
+  /**
+   * Apply oversampling and rescoring to quantized vectors
    * @availability stack since=8.18.0
    * @availability serverless
    */

specification/_types/Retriever.ts

@@ -124,14 +124,16 @@ export class KnnRetriever extends RetrieverBase {
   k: integer
   /** Number of nearest neighbor candidates to consider per shard. */
   num_candidates: integer
-  /** The percentage of vectors to explore per shard while doing knn search with bbq_disk
+  /**
+   * The percentage of vectors to explore per shard while doing knn search with bbq_disk
    * @availability stack since=9.2.0
    * @availability serverless
    */
   visit_percentage?: float
   /** The minimum similarity required for a document to be considered a match.  */
   similarity?: float
-  /** Apply oversampling and rescoring to quantized vectors
+  /**
+   * Apply oversampling and rescoring to quantized vectors
    * @availability stack since=8.18.0
    * @availability serverless
    */
@@ -144,7 +146,10 @@ export class KnnRetriever extends RetrieverBase {
 export class RRFRetrieverComponent {
   /** The nested retriever configuration. */
   retriever: RetrieverContainer
-  /** Weight multiplier for this retriever's contribution to the RRF score. Higher values increase influence. Defaults to 1.0 if not specified. Must be non-negative. @server_default 1.0 */
+  /**
+   * Weight multiplier for this retriever's contribution to the RRF score. Higher values increase influence. Defaults to 1.0 if not specified. Must be non-negative.
+   * @server_default 1.0
+   */
   weight?: float
 }
 
@@ -176,7 +181,8 @@ export class TextSimilarityReranker extends RetrieverBase {
   inference_text: string
   /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text. */
   field: string
-  /** Whether to rescore on only the best matching chunks.
+  /**
+   * Whether to rescore on only the best matching chunks.
    * @availability stack since=9.2.0 stability=beta
    * @availability serverless stability=beta
    */

specification/_types/TokenPruningConfig.ts

@@ -20,15 +20,18 @@
 import { float, integer } from '@_types/Numeric'
 
 export class TokenPruningConfig {
-  /** Tokens whose frequency is more than this threshold times the average frequency of all tokens in the specified field are considered outliers and pruned.
+  /**
+   * Tokens whose frequency is more than this threshold times the average frequency of all tokens in the specified field are considered outliers and pruned.
    * @server_default 5
    */
   tokens_freq_ratio_threshold?: integer
-  /** Tokens whose weight is less than this threshold are considered nonsignificant and pruned.
+  /**
+   * Tokens whose weight is less than this threshold are considered nonsignificant and pruned.
    * @server_default 0.4
    */
   tokens_weight_threshold?: float
-  /** Whether to only score pruned tokens, vs only scoring kept tokens.
+  /**
+   * Whether to only score pruned tokens, vs only scoring kept tokens.
    * @server_default false
    */
   only_score_pruned_tokens?: boolean

specification/_types/aggregations/Aggregate.ts

@@ -451,7 +451,8 @@ export class HistogramBucket extends MultiBucketBase {
   key: double
 }
 
-/** @variant name=date_histogram
+/**
+ * @variant name=date_histogram
  * @ext_doc_id search-aggregations-bucket-datehistogram-aggregation
  */
 export class DateHistogramAggregate extends MultiBucketAggregateBase<DateHistogramBucket> {}

specification/_types/aggregations/AggregationContainer.ts

@@ -457,7 +457,6 @@ export class AggregationContainer {
    * Sampling provides significant speed improvement at the cost of accuracy.
    * @ext_doc_id search-aggregations-random-sampler-aggregation
    * @availability stack since=8.1.0 stability=experimental
-
    */
   random_sampler?: RandomSamplerAggregation
   /**