Configure UpdateForV10 tag with eslint-plugin-jsdoc

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
  /**

specification/_types/analysis/StopWords.ts

@@ -61,6 +61,6 @@ export enum StopWordLanguage {
  * Language value, such as _arabic_ or _thai_. Defaults to _english_.
  * Each language value corresponds to a predefined list of stop words in Lucene. See Stop words by language for supported language values and their stop words.
  * Also accepts an array of stop words.
- * @class_serializer: StopWordsFormatter
+ * @class_serializer StopWordsFormatter
  */
 export type StopWords = StopWordLanguage | string[]