[DOCS] Reformats ML update APIs (#45253)

docs/java-rest/high-level/ml/update-filter.asciidoc

@@ -4,14 +4,13 @@
 :response: PutFilterResponse
 --
 [id="{upid}-{api}"]
-=== Update Filter API
+=== Update filter API
 
-The Update Filter API can be used to update an existing {ml} filter
-in the cluster. The API accepts a +{request}+ object
-as a request and returns a +{response}+.
+Updates an existing {ml} filter in the cluster. The API accepts a +{request}+
+object as a request and returns a +{response}+.
 
 [id="{upid}-{api}-request"]
-==== Update Filter Request
+==== Update filter request
 
 A +{request}+ requires the following argument:
 
@@ -19,28 +18,28 @@ A +{request}+ requires the following argument:
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> The id of the existing {ml} filter
+<1> The id of the existing {ml} filter.
 
-==== Optional Arguments
+==== Optional arguments
 The following arguments are optional:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-description]
 --------------------------------------------------
-<1> The updated description of the {ml} filter
+<1> The updated description of the {ml} filter.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-add-items]
 --------------------------------------------------
-<1> The list of items to add to the {ml} filter
+<1> The list of items to add to the {ml} filter.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-remove-items]
 --------------------------------------------------
-<1> The list of items to remove from the {ml} filter
+<1> The list of items to remove from the {ml} filter. 
 
 include::../execution.asciidoc[]
 
@@ -54,4 +53,4 @@ the updated {ml} filter if it has been successfully updated.
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> The updated `MlFilter`
+<1> The updated `MlFilter`.

docs/java-rest/high-level/ml/update-job.asciidoc

@@ -4,14 +4,13 @@
 :response: PutJobResponse
 --
 [id="{upid}-{api}"]
-=== Update Job API
+=== Update {anomaly-job} API
 
-The Update Job API provides the ability to update a {ml} job.
-It accepts a +{request}+ object and responds
-with a +{response}+ object.
+Provides the ability to update an {anomaly-job}.
+It accepts a +{request}+ object and responds with a +{response}+ object.
 
 [id="{upid}-{api}-request"]
-==== Update Job Request
+==== Update {anomaly-job} request
 
 An +{request}+ object gets created with a `JobUpdate` object.
 
@@ -19,43 +18,44 @@ An +{request}+ object gets created with a `JobUpdate` object.
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> Constructing a new request referencing a `JobUpdate` object
+<1> Constructing a new request referencing a `JobUpdate` object.
 
-==== Optional Arguments
+==== Optional arguments
 
-The `JobUpdate` object has many optional arguments with which to update an existing {ml}
-job. An existing, non-null `jobId` must be referenced in its creation.
+The `JobUpdate` object has many optional arguments with which to update an
+existing {anomaly-job}. An existing, non-null `jobId` must be referenced in its 
+creation.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-options]
 --------------------------------------------------
-<1> Mandatory, non-null `jobId` referencing an existing {ml} job
-<2> Updated description
-<3> Updated analysis limits
-<4> Updated background persistence interval
-<5> Updated analysis config's categorization filters
-<6> Updated detectors through the `JobUpdate.DetectorUpdate` object
-<7> Updated group membership
-<8> Updated result retention
-<9> Updated model plot configuration
-<10> Updated model snapshot retention setting
-<11> Updated custom settings
-<12> Updated renormalization window
+<1> Mandatory, non-null `jobId` referencing an existing {anomaly-job}.
+<2> Updated description.
+<3> Updated analysis limits. 
+<4> Updated background persistence interval.
+<5> Updated analysis config's categorization filters.
+<6> Updated detectors through the `JobUpdate.DetectorUpdate` object.
+<7> Updated group membership.
+<8> Updated result retention.
+<9> Updated model plot configuration.
+<10> Updated model snapshot retention setting.
+<11> Updated custom settings.
+<12> Updated renormalization window.
 
 Included with these options are specific optional `JobUpdate.DetectorUpdate` updates.
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-detector-options]
 --------------------------------------------------
-<1> The index of the detector. `O` means unknown
-<2> The optional description of the detector
-<3> The `DetectionRule` rules that apply to this detector
+<1> The index of the detector. `O` means unknown.
+<2> The optional description of the detector.
+<3> The `DetectionRule` rules that apply to this detector.
 
 include::../execution.asciidoc[]
 
 [id="{upid}-{api}-response"]
-==== Update Job Response
+==== Update {anomaly-job} response
 
 A +{response}+ contains the updated `Job` object
 
@@ -63,4 +63,4 @@ A +{response}+ contains the updated `Job` object
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> `getResponse()` returns the updated `Job` object
+<1> `getResponse()` returns the updated `Job` object.

docs/java-rest/high-level/ml/update-model-snapshot.asciidoc

@@ -4,14 +4,13 @@
 :response: UpdateModelSnapshotResponse
 --
 [id="{upid}-{api}"]
-=== Update Model Snapshot API
+=== Update model snapshot API
 
-The Update Model Snapshot API provides the ability to update a {ml} model snapshot.
-It accepts a +{request}+ object and responds
-with a +{response}+ object.
+Provides the ability to update a {ml} model snapshot.
+It accepts a +{request}+ object and responds with a +{response}+ object.
 
 [id="{upid}-{api}-request"]
-==== Update Model Snapshot Request
+==== Update model snapshot request
 
 A +{request}+ requires the following arguments:
 
@@ -19,9 +18,10 @@ A +{request}+ requires the following arguments:
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> Constructing a new request referencing existing `jobId` and `snapshotId` values.
+<1> Constructing a new request referencing existing `jobId` and `snapshotId`
+values.
 
-==== Optional Arguments
+==== Optional arguments
 
 The following arguments are optional:
 
@@ -29,19 +29,19 @@ The following arguments are optional:
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-description]
 --------------------------------------------------
-<1> The updated description of the {ml} model snapshot
+<1> The updated description of the {ml} model snapshot.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-retain]
 --------------------------------------------------
-<1> The updated `retain` property of the {ml} model snapshot
+<1> The updated `retain` property of the {ml} model snapshot.
 
 
 include::../execution.asciidoc[]
 
 [id="{upid}-{api}-response"]
-==== Update Job Response
+==== Update model snapshot response
 
 A +{response}+ contains an acknowledgement of the update request and the full representation of the updated `ModelSnapshot` object
 
@@ -49,5 +49,5 @@ A +{response}+ contains an acknowledgement of the update request and the full re
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> An acknowledgement of the request
-<2> The updated `ModelSnapshot`
+<1> An acknowledgement of the request.
+<2> The updated `ModelSnapshot`.

docs/reference/ml/anomaly-detection/apis/update-job.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="platinum"]
 [[ml-update-job]]
-=== Update jobs API
+=== Update {anomaly-jobs} API
 ++++
 <titleabbrev>Update jobs</titleabbrev>
 ++++
 
-Updates certain properties of a job.
+Updates certain properties of an {anomaly-job}.
 
 [[ml-update-job-request]]
 ==== {api-request-title}
@@ -25,7 +25,7 @@ Updates certain properties of a job.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the job.
+  (Required, string) Identifier for the {anomaly-job}.
 
 [[ml-update-job-request-body]]
 ==== {api-request-body-title}
@@ -81,7 +81,7 @@ want to re-run this job with an increased `model_memory_limit`.
 --
 
 [[ml-detector-update]]
-==== Detector Update Objects
+==== Detector update objects
 
 A detector update object has the following properties:
 
@@ -128,8 +128,8 @@ POST _ml/anomaly_detectors/total-requests/_update
 // CONSOLE
 // TEST[skip:setup:server_metrics_job]
 
-When the job is updated, you receive a summary of the job configuration
-information, including the updated property values. For example:
+When the {anomaly-job} is updated, you receive a summary of the job
+configuration information, including the updated property values. For example:
 
 [source,js]
 ----

docs/reference/ml/anomaly-detection/apis/update-snapshot.asciidoc

@@ -25,7 +25,7 @@ Updates certain properties of a snapshot.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the job.
+  (Required, string) Identifier for the {anomaly-job}.
 
 `<snapshot_id>`::
   (Required, string) Identifier for the model snapshot.
@@ -42,8 +42,8 @@ The following properties can be updated after the model snapshot is created:
 `retain`::
   (Optional, boolean) If true, this snapshot will not be deleted during
   automatic cleanup of snapshots older than `model_snapshot_retention_days`.
-  Note that this snapshot will still be deleted when the job is deleted.
-  The default value is false.
+  Note that this snapshot will still be deleted when the {anomaly-job} is
+  deleted. The default value is false.
 
 [[ml-update-snapshot-example]]
 ==== {api-examples-title}

docs/reference/ml/anomaly-detection/apis/validate-detector.asciidoc

@@ -3,7 +3,7 @@
 [[ml-valid-detector]]
 === Validate detectors API
 ++++
-<titleabbrev>Validate detectors </titleabbrev>
+<titleabbrev>Validate detectors</titleabbrev>
 ++++
 
 Validates detector configuration information.
@@ -23,8 +23,8 @@ Validates detector configuration information.
 [[ml-valid-detector-desc]]
 ==== {api-description-title}
 
-The validate detectors API enables you validate the detector configuration
-before you create a job.
+This API enables you validate the detector configuration
+before you create an {anomaly-job}.
 
 [[ml-valid-detector-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/validate-job.asciidoc

@@ -1,12 +1,12 @@
 [role="xpack"]
 [testenv="platinum"]
 [[ml-valid-job]]
-=== Validate jobs API
+=== Validate {anomaly-jobs} API
 ++++
 <titleabbrev>Validate jobs</titleabbrev>
 ++++
 
-Validates job configuration information.
+Validates {anomaly-job} configuration information.
 
 [[ml-valid-job-request]]
 ==== {api-request-title}
@@ -23,14 +23,14 @@ Validates job configuration information.
 [[ml-valid-job-desc]]
 ==== {api-description-title}
 
-The validate jobs API enables you validate the job configuration before you
+This API enables you validate the {anomaly-job} configuration before you
 create the job.
 
 [[ml-valid-job-request-body]]
 ==== {api-request-body-title}
 
 For a list of the properties that you can specify in the body of this API,
-see <<ml-job-resource,Job Resources>>.
+see <<ml-job-resource>>.
 
 [[ml-valid-job-example]]
 ==== {api-examples-title}