More changes to java update-by-query api docs

docs/java-api/docs/update-by-query.asciidoc

@@ -39,8 +39,8 @@ the conflicting document was updated between the start of the `updateByQuery`
 and the time when it attempted to update the document. This is fine because
 that update will have picked up the online mapping update.
 
-Back to the API, `UpdateByQueryRequestBuilder` supports filtering the documents
+The `UpdateByQueryRequestBuilder` API supports filtering the updated documents,
-that are updated, limiting the total number updated, and updating documents
+limiting the total number of documents to update, and updating documents
 with a script:
 
 [source,java]
@@ -55,8 +55,8 @@ updateByQuery.source("source_index")
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-`UpdateByQueryRequestBuilder` also allows you direct access to the query used
+`UpdateByQueryRequestBuilder` also enables direct access to the query used
-to select the documents which you can use to change the default scroll size or
+to select the documents. You can use this access to change the default scroll size or
 otherwise modify the request for matching documents.
 
 [source,java]
@@ -81,8 +81,8 @@ updateByQuery.source("source_index").size(100)
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-In addition to changing the `_source` of the document (see above) the script
+In addition to changing the `_source` field for the document, you can use a
-can change the update action similarly to the Update API:
+script to change the action, similar to the Update API:
 
 [source,java]
 --------------------------------------------------
@@ -100,14 +100,14 @@ updateByQuery.source("source_index")
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-Just as in <<docs-update,Update API>> you can set `ctx.op` to change the
+As in the <<docs-update,Update API>>, you can set the value of `ctx.op` to change the
-operation that is executed:
+operation that executes:
 
 `noop`::
 
-Set `ctx.op = "noop"` if your script decides that it doesn't have to make any
+Set `ctx.op = "noop"` if your script doesn't make any
-changes. That will cause `updateByQuery` to omit that document from its updates.
+changes. The `updateByQuery` operaton then omits that document from the updates.
- This no operation will be reported in the `noop` counter in the
+This behavior increments the `noop` counter in the
 <<docs-update-by-query-response-body, response body>>.
 
 `delete`::
@@ -116,15 +116,14 @@ Set `ctx.op = "delete"` if your script decides that the document must be
 deleted. The deletion will be reported in the `deleted` counter in the
 <<docs-update-by-query-response-body, response body>>.
 
-Setting `ctx.op` to anything else is an error. Setting any
+Setting `ctx.op` to any other value generates an error. Setting any
-other field in `ctx` is an error.
+other field in `ctx` generates an error.
 
 This API doesn't allow you to move the documents it touches, just modify their
 source. This is intentional! We've made no provisions for removing the document
 from its original location.
 
-It's also possible to do this whole thing on multiple indexes and multiple
+You can also perform these operations on multiple indices and types at once, similar to the search API:
-types at once, just like the search API:
 
 [source,java]
 --------------------------------------------------
@@ -135,7 +134,7 @@ updateByQuery.source("foo", "bar").source().setTypes("a", "b");
 BulkIndexByScrollResponse response = updateByQuery.get();
 --------------------------------------------------
 
-If you provide `routing` then the routing is copied to the scroll query,
+If you provide a `routing` value then the process copies the routing value to the scroll query,
 limiting the process to the shards that match that routing value:
 
 [source,java]
@@ -201,28 +200,26 @@ client.admin().cluster().prepareCancelTasks().setActions(UpdateByQueryAction.NAM
 client.admin().cluster().prepareCancelTasks().setTaskId(taskId).get().getTasks()
 --------------------------------------------------
 
-The `taskId` can be found using the list tasks API above.
+Use the `list tasks` API to find the value of `taskId`.
-
-Cancelation should happen quickly but might take a few seconds. The task status
-API above will continue to list the task until it is wakes to cancel itself.
 
+Cancelling a request is typically a very fast process but can take up to a few seconds.
+The task status API continues to list the task until the cancellation is complete.
 
 [float]
 [[docs-update-by-query-rethrottle]]
 === Rethrottling
 
-The value of `requests_per_second` can be changed on a running update by query
+Use the `_rethrottle` API to change the value of `requests_per_second` on a running update:
-using the `_rethrottle` API:
 
 [source,java]
 --------------------------------------------------
 RethrottleAction.INSTANCE.newRequestBuilder(client).setTaskId(taskId).setRequestsPerSecond(2.0f).get();
 --------------------------------------------------
 
-The `taskId` can be found using the tasks API above.
+Use the `list tasks` API to find the value of `taskId`.
 
-Just like when setting it on the `updateByQuery` API `requests_per_second`
+As with the `updateByQuery` API, the value of `requests_per_second`
-can be either `Float.POSITIVE_INFINITY` to disable throttling or any positive
+can be any positive float value to set the level of the throttle, or `Float.POSITIVE_INFINITY` to disable throttling.
-float to throttle to that level. Rethrottling that speeds up the query takes
+A value of `requests_per_second` that speeds up the process takes
-effect immediately but rethrotting that slows down the query will take effect
+effect immediately. `requests_per_second` values that slow the query take effect
-on after completing the current batch. This prevents scroll timeouts.
+after completing the current batch in order to prevent scroll timeouts.