[DOCS] Edit task manager summaries (#3343)

(cherry picked from commit 2426d4e)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -33,14 +33,25 @@ export class TaskInfo {
   action: string
   cancelled?: boolean
   cancellable: boolean
+  /**
+   * Human readable text that identifies the particular request that the task is performing.
+   * For example, it might identify the search request being performed by a search task.
+   * Other kinds of tasks have different descriptions, like `_reindex` which has the source and the destination, or `_bulk` which just has the number of requests and the destination indices.
+   * Many requests will have only an empty description because more detailed information about the request is not easily available or particularly helpful in identifying the request.
+   */
   description?: string
   headers: Dictionary<string, string>
   id: long
   node: NodeId
   running_time?: Duration
   running_time_in_nanos: DurationValue<UnitNanos>
   start_time_in_millis: EpochTime<UnitMillis>
-  /** Task status information can vary wildly from task to task. */
+  /**
+   * The internal status of the task, which varies from task to task.
+   * The format also varies.
+   * While the goal is to keep the status for a particular task consistent from version to version, this is not always possible because sometimes the implementation changes.
+   * Fields might be removed from the status for a particular request so any parsing you do of the status might break in minor releases.
+   */
   status?: UserDefinedValue
   type: string
   parent_task_id?: TaskId

output/openapi/elasticsearch-serverless-openapi.json

@@ -21,6 +21,14 @@ import { RequestBase } from '@_types/Base'
 import { TaskId } from '@_types/common'
 
 /**
+ * Cancel a task.
+ * A task may continue to run for some time after it has been cancelled because it may not be able to safely stop its current activity straight away.
+ * It is also possible that Elasticsearch must complete its work on other tasks before it can process the cancellation.
+ * The get task information API will continue to list these cancelled tasks until they complete.
+ * The cancelled flag in the response indicates that the cancellation command has been processed and the task will stop as soon as possible.
+ *
+ * To troubleshoot why a cancelled task does not complete promptly, use the get task information API with the `?detailed` parameter to identify the other tasks the system is running.
+ * You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.
  * @rest_spec_name tasks.cancel
  * @availability stack since=2.3.0 stability=experimental
  * @availability serverless stability=experimental visibility=private

output/schema/schema.json

@@ -23,7 +23,7 @@ import { Duration } from '@_types/Time'
 
 /**
  * Get task information.
- * Returns information about the tasks currently executing in the cluster.
+ * Get information about a task currently running in the cluster.
  * @rest_spec_name tasks.get
  * @availability stack since=5.0.0 stability=experimental
  * @availability serverless stability=experimental visibility=public

specification/tasks/_types/TaskInfo.ts

@@ -23,11 +23,12 @@ import { Id, NodeIds } from '@_types/common'
 import { Duration } from '@_types/Time'
 
 /**
- * The task management API returns information about tasks currently executing on one or more nodes in the cluster.
+ * Get all tasks.
+ * Get information about the tasks currently running on one or more nodes in the cluster.
  * @rest_spec_name tasks.list
  * @availability stack since=2.3.0 stability=experimental
  * @availability serverless stability=experimental visibility=private
- * @cluster_privileges monitor, manage
+ * @cluster_privileges monitor
  * @doc_id tasks
  */
 export interface Request extends RequestBase {
@@ -38,6 +39,7 @@ export interface Request extends RequestBase {
     actions?: string | string[]
     /**
      * If `true`, the response includes detailed information about shard recoveries.
+     * This information is useful to distinguish tasks from each other but is more costly to run.
      * @server_default false
      */
     detailed?: boolean