[Backport 8.x] [OpenAPI] Improve analyze and async search summaries (#…

…3020)

specification/async_search/delete/AsyncSearchDeleteRequest.ts

@@ -21,8 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Deletes an async search by identifier.
- * If the search is still running, the search request will be cancelled.
+ * Delete an async search.
+ * If the asynchronous search is still running, it is cancelled.
  * Otherwise, the saved search results are deleted.
  * If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the `cancel_task` cluster privilege.
  * @rest_spec_name async_search.delete

specification/async_search/get/AsyncSearchGetRequest.ts

@@ -22,7 +22,8 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * Retrieves the results of a previously submitted async search request given its identifier.
+ * Get async search results.
+ * Retrieve the results of a previously submitted asynchronous search request.
  * If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
  * @rest_spec_name async_search.get
  * @availability stack since=7.7.0 stability=stable

specification/async_search/status/AsyncSearchStatusRequest.ts

@@ -21,8 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Id } from '@_types/common'
 
 /**
- * Get async search status
- * Retrieves the status of a previously submitted async search request given its identifier, without retrieving search results.
+ * Get async search status.
+ * Retrieve the status of a previously submitted async search request given its identifier, without retrieving search results.
  * If the Elasticsearch security features are enabled, use of this API is restricted to the `monitoring_user` role.
  * @rest_spec_name async_search.status
  * @availability stack since=7.11.0 stability=stable

specification/async_search/submit/AsyncSearchSubmitRequest.ts

@@ -53,10 +53,12 @@ import { Sort, SortResults } from '@_types/sort'
 import { Duration } from '@_types/Time'
 
 /**
- * Runs a search request asynchronously.
- * When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field, hence partial results become available following the sort criteria that was requested.
- * Warning: Async search does not support scroll nor search requests that only include the suggest section.
- * By default, Elasticsearch doesn’t allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
+ * Run an async search.
+ * When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field. Partial results become available following the sort criteria that was requested.
+ *
+ * Warning: Asynchronous search does not support scroll or search requests that include only the suggest section.
+ *
+ * By default, Elasticsearch does not allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
  * The maximum allowed size for a stored async search response can be set by changing the `search.max_async_search_response_size` cluster level setting.
  * @rest_spec_name async_search.submit
  * @availability stack since=7.7.0 stability=stable

specification/indices/analyze/IndicesAnalyzeRequest.ts

@@ -25,7 +25,8 @@ import { Field, IndexName } from '@_types/common'
 import { TextToAnalyze } from './types'
 
 /**
- * Performs analysis on a text string and returns the resulting tokens.
+ * Get tokens from text analysis.
+ * The analyze API performs [analysis](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis.html) on a text string and returns the resulting tokens.
  * @doc_id indices-analyze
  * @rest_spec_name indices.analyze
  * @availability stack stability=stable