Feature/hlrc ml docs cleanup (#34316)

* HLRC: ML Add preview datafeed api

* Changing deprecation handling for parser

* Removing some duplication in docs, will address other APIs in another PR

* HLRC: ML Cleanup docs

* updating get datafeed stats docs

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

@@ -1,18 +1,23 @@
-[[java-rest-high-x-pack-ml-close-job]]
+--
+:api: close-job
+:request: CloseJobRequest
+:response: CloseJobResponse
+--
+[id="{upid}-{api}"]
 === Close Job API
 
 The Close Job API provides the ability to close {ml} jobs in the cluster.
-It accepts a `CloseJobRequest` object and responds
-with a `CloseJobResponse` object.
+It accepts a +{request}+ object and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-close-job-request]]
+[id="{upid}-{api}-request"]
 ==== Close Job Request
 
-A `CloseJobRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing existing job IDs
 <2> Optionally used to close a failed job, or to forcefully close a job
@@ -22,38 +27,14 @@ which has not responded to its initial close request.
 <4> Optionally setting the `timeout` value for how long the
 execution should wait for the job to be closed.
 
-[[java-rest-high-x-pack-ml-close-job-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
+[id="{upid}-{api}-response"]
+==== Close Job Response
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
-<1> `isClosed()` from the `CloseJobResponse` indicates if the job was successfully
+<1> `isClosed()` from the +{response}+ indicates if the job was successfully
 closed or not.
 
-[[java-rest-high-x-pack-ml-close-job-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-execute-async]
---------------------------------------------------
-<1> The `CloseJobRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `CloseJobResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-close-job-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/delete-calendar.asciidoc

@@ -1,59 +1,33 @@
-[[java-rest-high-x-pack-ml-delete-calendar]]
+--
+:api: delete-calendar
+:request: DeleteCalendarRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-{api}"]
 === Delete Calendar API
 Delete a {ml} calendar.
-The API accepts a `DeleteCalendarRequest` and responds
-with a `AcknowledgedResponse` object.
+The API accepts a +{request}+ and responds
+with a +{response}+ object.
 
-[[java-rest-high-x-pack-ml-delete-calendar-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Calendar Request
 
 A `DeleteCalendar` object requires a non-null `calendarId`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-request]
+include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Constructing a new request referencing an existing Calendar
 
-[[java-rest-high-x-pack-ml-delete-calendar-response]]
+[id="{upid}-{api}-response"]
 ==== Delete Calendar Response
 
-The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
+The returned +{response}+ object indicates the acknowledgement of the request:
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-response]
+include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
 <1> `isAcknowledged` was the deletion request acknowledged or not
 
-[[java-rest-high-x-pack-ml-delete-calendar-execution]]
-==== Execution
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-delete-calendar-async]]
-==== Delete Calendar Asynchronously
-
-This request can also be made asynchronously.
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-execute-async]
----------------------------------------------------
-<1> The `DeleteCalendarRequest` to execute and the `ActionListener` to alert on completion or error.
-
-The deletion request returns immediately. Once the request is completed, the `ActionListener` is
-called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
-making the request.
-
-A typical listener for a `DeleteCalendarRequest` could be defined as follows:
-
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-calendar-listener]
----------------------------------------------------
-<1> The action to be taken when it is completed
-<2> What to do when a failure occurs
+include::../execution.asciidoc[]

docs/java-rest/high-level/ml/delete-datafeed.asciidoc

@@ -1,49 +1,32 @@
-[[java-rest-high-x-pack-ml-delete-datafeed]]
+--
+:api: delete-datafeed 
+:request: DeleteDatafeedRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-delete-datafeed"]
 === Delete Datafeed API
 
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Datafeed Request
 
-A `DeleteDatafeedRequest` object requires a non-null `datafeedId` and can optionally set `force`.
-Can be executed as follows:
+A +{request}+ object requires a non-null `datafeedId` and can optionally set `force`.
 
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request]
+include-tagged::{doc-tests-file}[{api}-request]
 ---------------------------------------------------
 <1> Use to forcefully delete a started datafeed;
 this method is quicker than stopping and deleting the datafeed.
 Defaults to `false`.
 
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-response]]
+include::../execution.asciidoc[]
+
+[id="{upid}-{api}-response"]
 ==== Delete Datafeed Response
 
-The returned `AcknowledgedResponse` object indicates the acknowledgement of the request:
+The returned +{response}+ object indicates the acknowledgement of the request:
 ["source","java",subs="attributes,callouts,macros"]
 ---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-response]
+include-tagged::{doc-tests-file}[{api}-response]
 ---------------------------------------------------
 <1> `isAcknowledged` was the deletion request acknowledged or not
-
-[[java-rest-high-x-pack-machine-learning-delete-datafeed-async]]
-==== Delete Datafeed Asynchronously
-
-This request can also be made asynchronously.
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-async]
----------------------------------------------------
-<1> The `DeleteDatafeedRequest` to execute and the `ActionListener` to alert on completion or error.
-
-The deletion request returns immediately. Once the request is completed, the `ActionListener` is
-called back using the `onResponse` or `onFailure`. The latter indicates some failure occurred when
-making the request.
-
-A typical listener for a `DeleteDatafeedRequest` could be defined as follows:
-
-["source","java",subs="attributes,callouts,macros"]
----------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-delete-ml-datafeed-request-listener]
----------------------------------------------------
-<1> The action to be taken when it is completed
-<2> What to do when a failure occurs

docs/java-rest/high-level/ml/delete-forecast.asciidoc

@@ -1,20 +1,25 @@
-[[java-rest-high-x-pack-ml-delete-forecast]]
+--
+:api: delete-forecast 
+:request: DeleteForecastRequest
+:response: AcknowledgedResponse
+--
+[id="{upid}-{api}"]
 === Delete Forecast API
 
 The Delete Forecast API provides the ability to delete a {ml} job's
 forecast in the cluster.
-It accepts a `DeleteForecastRequest` object and responds
-with an `AcknowledgedResponse` object.
+It accepts a +{request}+ object and responds
+with an +{response}+ object.
 
-[[java-rest-high-x-pack-ml-delete-forecast-request]]
+[id="{upid}-{api}-request"]
 ==== Delete Forecast Request
 
-A `DeleteForecastRequest` object gets created with an existing non-null `jobId`.
+A +{request}+ object gets created with an existing non-null `jobId`.
 All other fields are optional for the request.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 <1> Constructing a new request referencing an existing `jobId`
 
@@ -24,55 +29,23 @@ The following arguments are optional.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-request-options]
+include-tagged::{doc-tests-file}[{api}-request-options]
 --------------------------------------------------
 <1> Sets the specific forecastIds to delete, can be set to `_all` to indicate ALL forecasts for the given
 `jobId` 
 <2> Set the timeout for the request to respond, default is 30 seconds 
 <3> Set the `allow_no_forecasts` option. When `true` no error will be returned if an `_all`
-request finds no forecasts. It defaults to `true` 
+request finds no forecasts. It defaults to `true`
 
-[[java-rest-high-x-pack-ml-delete-forecast-execution]]
-==== Execution
-
-The request can be executed through the `MachineLearningClient` contained
-in the `RestHighLevelClient` object, accessed via the `machineLearningClient()` method.
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute]
---------------------------------------------------
-
-[[java-rest-high-x-pack-ml-delete-forecast-execution-async]]
-==== Asynchronous Execution
-
-The request can also be executed asynchronously:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-execute-async]
---------------------------------------------------
-<1> The `DeleteForecastRequest` to execute and the `ActionListener` to use when
-the execution completes
-
-The method does not block and returns immediately. The passed `ActionListener` is used
-to notify the caller of completion. A typical `ActionListener` for `AcknowledgedResponse` may
-look like
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-listener]
---------------------------------------------------
-<1> `onResponse` is called back when the action is completed successfully
-<2> `onFailure` is called back when some unexpected error occurs
-
-[[java-rest-high-x-pack-ml-delete-forecast-response]]
+[id="{upid}-{api}-response"]
 ==== Delete Forecast Response
 
-An `AcknowledgedResponse` contains an acknowledgement of the forecast(s) deletion
+An +{response}+ contains an acknowledgement of the forecast(s) deletion
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MlClientDocumentationIT.java[x-pack-ml-delete-forecast-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> `isAcknowledged()` indicates if the forecast was successfully deleted or not.
+
+include::../execution.asciidoc[]