Docs: Cut down on high level rest client copy-and-paste-ness (#34125)

* Anchors

* includes

* get settings

* more

* More

Author: nik9000

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/ClusterClientDocumentationIT.java

@@ -55,22 +55,8 @@
 import static org.hamcrest.Matchers.notNullValue;
 
 /**
- * This class is used to generate the Java Cluster API documentation.
- * You need to wrap your code between two tags like:
- * // tag::example
- * // end::example
- *
- * Where example is your tag name.
- *
- * Then in the documentation, you can extract what is between tag and end tags with
- * ["source","java",subs="attributes,callouts,macros"]
- * --------------------------------------------------
- * include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[example]
- * --------------------------------------------------
- *
- * The column width of the code block is 84. If the code contains a line longer
- * than 84, the line will be cut and a horizontal scroll bar will be displayed.
- * (the code indentation of the tag is not included in the width)
+ * Documentation for Cluster APIs in the high level java client.
+ * Code wrapped in {@code tag} and {@code end} tags is included in the docs.
  */
 public class ClusterClientDocumentationIT extends ESRestHighLevelClientTestCase {
 

docs/java-rest/high-level/cluster/get_settings.asciidoc

@@ -1,92 +1,63 @@
-[[java-rest-high-cluster-get-settings]]
+--
+:api: get-settings
+:request: ClusterGetSettingsRequest
+:response: ClusterGetSettingsResponse
+--
+
+[id="{upid}-{api}"]
 === Cluster Get Settings API
 
 The Cluster Get Settings API allows to get the cluster wide settings.
 
-[[java-rest-high-cluster-get-settings-request]]
+[id="{upid}-{api}-request"]
 ==== Cluster Get Settings Request
 
-A `ClusterGetSettingsRequest`:
+A +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 
 ==== Optional arguments
 The following arguments can optionally be provided:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-includeDefaults]
+include-tagged::{doc-tests-file}[{api}-request-includeDefaults]
 --------------------------------------------------
 <1> By default only those settings that were explicitly set are returned. Setting this to true also returns
 the default settings.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-local]
+include-tagged::{doc-tests-file}[{api}-request-local]
 --------------------------------------------------
 <1> By default the request goes to the master of the cluster to get the latest results. If local is specified it gets
 the results from whichever node the request goes to.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-request-masterTimeout]
+include-tagged::{doc-tests-file}[{api}-request-masterTimeout]
 --------------------------------------------------
 <1> Timeout to connect to the master node as a `TimeValue`
 <2> Timeout to connect to the master node as a `String`
 
-[[java-rest-high-cluster-get-settings-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute]
---------------------------------------------------
-<1> Execute the request and get back the response in a `ClusterGetSettingsResponse` object.
-
-[[java-rest-high-cluster-get-settings-async]]
-==== Asynchronous Execution
-
-The asynchronous execution of a cluster get settings requires both the
-`ClusterGetSettingsRequest` instance and an `ActionListener` instance to be
-passed to the asynchronous method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-async]
---------------------------------------------------
-<1> The `ClusterGetSettingsRequest` to execute and the `ActionListener`
-to use when the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
+include::../execution.asciidoc[]
 
-A typical listener for `ClusterGetSettingsResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of a failure. The raised exception is provided as an argument
-
-[[java-rest-high-cluster-get-settings-response]]
+[id="{upid}-{api}-response"]
 ==== Cluster Get Settings Response
 
-The returned `ClusterGetSettingsResponse` allows to retrieve information about the
+The returned +{response}+ allows to retrieve information about the
 executed operation as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[get-settings-response]
+include-tagged::{doc-tests-file}[{api}-response]
 --------------------------------------------------
 <1> Get the persistent settings.
 <2> Get the transient settings.
 <3> Get the default settings (returns empty settings if `includeDefaults` was not set to `true`).
 <4> Get the value as a `String` for a particular setting. The order of searching is first in `persistentSettings` then in
 `transientSettings` and finally, if not found in either, in `defaultSettings`.
+

docs/java-rest/high-level/cluster/health.asciidoc

@@ -1,16 +1,22 @@
-[[java-rest-high-cluster-health]]
+--
+:api: health
+:request: ClusterHealthRequest
+:response: ClusterHealthResponse
+--
+
+[id="{upid}-{api}"]
 === Cluster Health API
 
 The Cluster Health API allows getting cluster health.
 
-[[java-rest-high-cluster-health-request]]
+[id="{upid}-{api}-request"]
 ==== Cluster Health Request
 
-A `ClusterHealthRequest`:
+A +{request}+:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request]
+include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
 There are no required parameters. By default, the client will check all indices and will not wait
 for any events.
@@ -21,14 +27,14 @@ Indices which should be checked can be passed in the constructor:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-ctr]
+include-tagged::{doc-tests-file}[{api}-request-indices-ctr]
 --------------------------------------------------
 
 Or using the corresponding setter method:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-indices-setter]
+include-tagged::{doc-tests-file}[{api}-request-indices-setter]
 --------------------------------------------------
 
 ==== Other parameters
@@ -37,139 +43,104 @@ Other parameters can be passed only through setter methods:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-timeout]
+include-tagged::{doc-tests-file}[{api}-request-timeout]
 --------------------------------------------------
 <1> Timeout for the request as a `TimeValue`. Defaults to 30 seconds
 <2> As a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-master-timeout]
+include-tagged::{doc-tests-file}[{api}-request-master-timeout]
 --------------------------------------------------
 <1> Timeout to connect to the master node as a `TimeValue`. Defaults to the same as `timeout`
 <2> As a `String`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-status]
+include-tagged::{doc-tests-file}[{api}-request-wait-status]
 --------------------------------------------------
 <1> The status to wait (e.g. `green`, `yellow`, or `red`). Accepts a `ClusterHealthStatus` value.
 <2> Using predefined method
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-events]
+include-tagged::{doc-tests-file}[{api}-request-wait-events]
 --------------------------------------------------
 <1> The priority of the events to wait for. Accepts a `Priority` value.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-level]
+include-tagged::{doc-tests-file}[{api}-request-level]
 --------------------------------------------------
-<1> The level of detail of the returned health information. Accepts a `ClusterHealthRequest.Level` value.
+<1> The level of detail of the returned health information. Accepts a +{request}.Level+ value.
 Default value is `cluster`.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-relocation]
+include-tagged::{doc-tests-file}[{api}-request-wait-relocation]
 --------------------------------------------------
 <1> Wait for 0 relocating shards. Defaults to `false`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-initializing]
+include-tagged::{doc-tests-file}[{api}-request-wait-initializing]
 --------------------------------------------------
 <1> Wait for 0 initializing shards. Defaults to `false`
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-nodes]
+include-tagged::{doc-tests-file}[{api}-request-wait-nodes]
 --------------------------------------------------
 <1> Wait for `N` nodes in the cluster. Defaults to `0`
 <2> Using `>=N`, `<=N`, `>N` and `<N` notation
 <3> Using `ge(N)`, `le(N)`, `gt(N)`, `lt(N)` notation
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-wait-active]
+include-tagged::{doc-tests-file}[{api}-request-wait-active]
 --------------------------------------------------
 
 <1> Wait for all shards to be active in the cluster
 <2> Wait for `N` shards to be active in the cluster
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-request-local]
+include-tagged::{doc-tests-file}[{api}-request-local]
 --------------------------------------------------
 <1> Non-master node can be used for this request. Defaults to `false`
 
-[[java-rest-high-cluster-health-sync]]
-==== Synchronous Execution
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute]
---------------------------------------------------
-
-[[java-rest-high-cluster-health-async]]
-==== Asynchronous Execution
-
-The asynchronous execution of a cluster health request requires both the
-`ClusterHealthRequest` instance and an `ActionListener` instance to be
-passed to the asynchronous method:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-async]
---------------------------------------------------
-<1> The `ClusterHealthRequest` to execute and the `ActionListener` to use
-when the execution completes
-
-The asynchronous method does not block and returns immediately. Once it is
-completed the `ActionListener` is called back using the `onResponse` method
-if the execution successfully completed or using the `onFailure` method if
-it failed.
-
-A typical listener for `ClusterHealthResponse` looks like:
-
-["source","java",subs="attributes,callouts,macros"]
---------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-execute-listener]
---------------------------------------------------
-<1> Called when the execution is successfully completed. The response is
-provided as an argument
-<2> Called in case of a failure. The raised exception is provided as an argument
+include::../execution.asciidoc[]
 
-[[java-rest-high-cluster-health-response]]
+[id="{upid}-{api}-response"]
 ==== Cluster Health Response
 
-The returned `ClusterHealthResponse` contains the next information about the
+The returned +{response}+ contains the next information about the
 cluster:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-general]
+include-tagged::{doc-tests-file}[{api}-response-general]
 --------------------------------------------------
 <1> Name of the cluster
 <2> Cluster status (`green`, `yellow` or `red`)
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-request-status]
+include-tagged::{doc-tests-file}[{api}-response-request-status]
 --------------------------------------------------
 <1> Whether request was timed out while processing
 <2> Status of the request (`OK` or `REQUEST_TIMEOUT`). Other errors will be thrown as exceptions
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-nodes]
+include-tagged::{doc-tests-file}[{api}-response-nodes]
 --------------------------------------------------
 <1> Number of nodes in the cluster
 <2> Number of data nodes in the cluster
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shards]
+include-tagged::{doc-tests-file}[{api}-response-shards]
 --------------------------------------------------
 <1> Number of active shards
 <2> Number of primary active shards
@@ -181,26 +152,26 @@ include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-sh
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-task]
+include-tagged::{doc-tests-file}[{api}-response-task]
 --------------------------------------------------
 <1> Maximum wait time of all tasks in the queue
 <2> Number of currently pending tasks
 <3> Number of async fetches that are currently ongoing
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-indices]
+include-tagged::{doc-tests-file}[{api}-response-indices]
 --------------------------------------------------
 <1> Detailed information about indices in the cluster
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-index]
+include-tagged::{doc-tests-file}[{api}-response-index]
 --------------------------------------------------
 <1> Detailed information about a specific index
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/ClusterClientDocumentationIT.java[health-response-shard-details]
+include-tagged::{doc-tests-file}[{api}-response-shard-details]
 --------------------------------------------------
 <1> Detailed information about a specific shard