Update task management docs to reflect the latest changes in the interface

docs/reference/cluster.asciidoc

@@ -45,7 +45,7 @@ include::cluster/nodes-stats.asciidoc[]
 
 include::cluster/nodes-info.asciidoc[]
 
-include::cluster/nodes-task.asciidoc[]
+include::cluster/tasks.asciidoc[]
 
 include::cluster/nodes-hot-threads.asciidoc[]
 

docs/reference/cluster/pending.asciidoc

@@ -5,6 +5,11 @@ The pending cluster tasks API returns a list of any cluster-level changes
 (e.g. create index, update mapping, allocate or fail shard) which have not yet
 been executed.
 
+NOTE: This API returns a list of any pending updates to the cluster state. These are distinct from the tasks reported by the
+<<tasks,Task Management API>> which include periodic tasks and tasks initiated by the user, such as node stats, search queries, or create
+index requests. However, if a user-initiated task such as a create index command causes a cluster state update, the activity of this task
+might be reported by both task api and pending cluster tasks API.
+
 [source,js]
 --------------------------------------------------
 $ curl -XGET 'http://localhost:9200/_cluster/pending_tasks'

docs/reference/cluster/tasks.asciidoc

@@ -0,0 +1,103 @@
+[[tasks]]
+== Task Management API
+
+experimental[The Task Management API is new and should still be considered experimental.  The API may change in ways that are not backwards compatible]
+
+[float]
+=== Current Tasks Information
+
+The task management API allows to retrieve information about the tasks currently
+executing on one or more nodes in the cluster.
+
+[source,js]
+--------------------------------------------------
+GET /_tasks <1>
+GET /_tasks?nodes=nodeId1,nodeId2 <2>
+GET /_tasks?nodes=nodeId1,nodeId2&actions=cluster:* <3>
+--------------------------------------------------
+// AUTOSENSE
+
+<1> Retrieves all tasks currently running on all nodes in the cluster.
+<2> Retrieves all tasks running on nodes `nodeId1` and `nodeId2`.  See <<cluster-nodes>> for more info about how to select individual nodes.
+<3> Retrieves all cluster-related tasks running on nodes `nodeId1` and `nodeId2`.
+
+The result will look similar to the following:
+
+[source,js]
+--------------------------------------------------
+{
+  "nodes" : {
+    "oTUltX4IQMOUUVeiohTt8A" : {
+      "name" : "Tamara Rahn",
+      "transport_address" : "127.0.0.1:9300",
+      "host" : "127.0.0.1",
+      "ip" : "127.0.0.1:9300",
+      "tasks" : {
+        "oTUltX4IQMOUUVeiohTt8A:124" : {
+          "node" : "oTUltX4IQMOUUVeiohTt8A",
+          "id" : 124,
+          "type" : "direct",
+          "action" : "cluster:monitor/tasks/lists[n]",
+          "start_time_in_millis" : 1458585884904,
+          "running_time_in_nanos" : 47402,
+          "parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
+        },
+        "oTUltX4IQMOUUVeiohTt8A:123" : {
+          "node" : "oTUltX4IQMOUUVeiohTt8A",
+          "id" : 123,
+          "type" : "transport",
+          "action" : "cluster:monitor/tasks/lists",
+          "start_time_in_millis" : 1458585884904,
+          "running_time_in_nanos" : 236042
+        }
+      }
+    }
+  }
+}
+
+--------------------------------------------------
+
+It is also possible to retrieve information for a particular task, or all children of a particular
+tasks using the following two commands:
+
+[source,js]
+--------------------------------------------------
+GET /_tasks/taskId1
+GET /_tasks?parent_task_id=parentTaskId1
+--------------------------------------------------
+// AUTOSENSE
+
+The task API can be also used to wait for completion of a particular task. The following call will
+block for 10 seconds or until the task with id `oTUltX4IQMOUUVeiohTt8A:12345` is completed.
+
+[source,js]
+--------------------------------------------------
+GET /_tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&timeout=10s
+--------------------------------------------------
+// AUTOSENSE
+
+
+[float]
+=== Task Cancellation
+
+If a long-running task supports cancellation, it can be cancelled by the following command:
+
+[source,js]
+--------------------------------------------------
+POST /_tasks/taskId1/_cancel
+--------------------------------------------------
+// AUTOSENSE
+
+The task cancellation command supports the same task selection parameters as the list tasks command, so multiple tasks
+can be cancelled at the same time. For example, the following command will cancel all reindex tasks running on the
+nodes `nodeId1` and `nodeId2`.
+
+[source,js]
+--------------------------------------------------
+POST /_tasks/_cancel?node_id=nodeId1,nodeId2&actions=*reindex
+--------------------------------------------------
+// AUTOSENSE
+
+
+
+

docs/reference/docs/reindex.asciidoc

@@ -390,7 +390,7 @@ from aborting the operation.
 === Works with the Task API
 
 While Reindex is running you can fetch their status using the
-<<nodes-task,Nodes Task API>>:
+<<tasks,Task API>>:
 
 [source,js]
 --------------------------------------------------
@@ -413,24 +413,26 @@ The responses looks like:
         "testattr" : "test",
         "portsfile" : "true"
       },
-      "tasks" : [ {
-        "node" : "r1A2WoRbTwKZ516z6NEs5A",
-        "id" : 36619,
-        "type" : "transport",
-        "action" : "indices:data/write/reindex",
-        "status" : {    <1>
-          "total" : 6154,
-          "updated" : 3500,
-          "created" : 0,
-          "deleted" : 0,
-          "batches" : 36,
-          "version_conflicts" : 0,
-          "noops" : 0,
-          "retries": 0,
-          "throttled_millis": 0
-        },
-        "description" : ""
-      } ]
+      "tasks" : {
+        "r1A2WoRbTwKZ516z6NEs5A:36619" : {
+          "node" : "r1A2WoRbTwKZ516z6NEs5A",
+          "id" : 36619,
+          "type" : "transport",
+          "action" : "indices:data/write/reindex",
+          "status" : {    <1>
+            "total" : 6154,
+            "updated" : 3500,
+            "created" : 0,
+            "deleted" : 0,
+            "batches" : 36,
+            "version_conflicts" : 0,
+            "noops" : 0,
+            "retries": 0,
+            "throttled_millis": 0
+          },
+          "description" : ""
+        }
+      }
     }
   }
 }

docs/reference/docs/update-by-query.asciidoc

@@ -235,11 +235,11 @@ from aborting the operation.
 === Works with the Task API
 
 While Update By Query is running you can fetch their status using the
-<<nodes-task,Nodes Task API>>:
+<<tasks,Task API>>:
 
 [source,js]
 --------------------------------------------------
-POST /_tasks/?pretty&detailed=true&action=byquery
+POST /_tasks/?pretty&detailed=true&action=*byquery
 --------------------------------------------------
 // AUTOSENSE
 
@@ -258,24 +258,26 @@ The responses looks like:
         "testattr" : "test",
         "portsfile" : "true"
       },
-      "tasks" : [ {
-        "node" : "r1A2WoRbTwKZ516z6NEs5A",
-        "id" : 36619,
-        "type" : "transport",
-        "action" : "indices:data/write/update/byquery",
-        "status" : {    <1>
-          "total" : 6154,
-          "updated" : 3500,
-          "created" : 0,
-          "deleted" : 0,
-          "batches" : 36,
-          "version_conflicts" : 0,
-          "noops" : 0,
-          "retries": 0,
-          "throttled_millis": 0
-        },
-        "description" : ""
-      } ]
+      "tasks" : {
+        "r1A2WoRbTwKZ516z6NEs5A:36619" : {
+          "node" : "r1A2WoRbTwKZ516z6NEs5A",
+          "id" : 36619,
+          "type" : "transport",
+          "action" : "indices:data/write/update/byquery",
+          "status" : {    <1>
+            "total" : 6154,
+            "updated" : 3500,
+            "created" : 0,
+            "deleted" : 0,
+            "batches" : 36,
+            "version_conflicts" : 0,
+            "noops" : 0,
+            "retries": 0,
+            "throttled_millis": 0
+          },
+          "description" : ""
+        }
+      }
     }
   }
 }