Docs: HighLevelRestClient#ping (#29070)

Add documentation for `HighLevelRestClient#ping`.

Relates to #28389

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MainDocumentationIT.java → client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MiscellaneousDocumentationIT.java

@@ -31,20 +31,10 @@ import org.elasticsearch.cluster.ClusterName;
 import java.io.IOException;
 
 /**
- * This class is used to generate the Java Main 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}/MainDocumentationIT.java[example]
- * --------------------------------------------------
+ * Documentation for miscellaneous APIs in the high level java client.
+ * Code wrapped in {@code tag} and {@code end} tags is included in the docs.
  */
-public class MainDocumentationIT extends ESRestHighLevelClientTestCase {
+public class MiscellaneousDocumentationIT extends ESRestHighLevelClientTestCase {
 
     public void testMain() throws IOException {
         RestHighLevelClient client = highLevelClient();
@@ -67,6 +57,14 @@ public class MainDocumentationIT extends ESRestHighLevelClientTestCase {
         }
     }
 
+    public void testPing() throws IOException {
+        RestHighLevelClient client = highLevelClient();
+        //tag::ping-execute
+        boolean response = client.ping();
+        //end::ping-execute
+        assertTrue(response);
+    }
+
     public void testInitializationFromClientBuilder() throws IOException {
         //tag::rest-high-level-client-init
         RestHighLevelClient client = new RestHighLevelClient(

docs/java-rest/high-level/getting-started.asciidoc

@@ -126,7 +126,7 @@ to be built as follows:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-init]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-init]
 --------------------------------------------------
 
 The high-level client will internally create the low-level client used to
@@ -139,7 +139,7 @@ method, which will close the internal `RestClient` instance.
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-close]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-close]
 --------------------------------------------------
 
 In the rest of this documentation about the Java High Level Client, the `RestHighLevelClient` instance

docs/java-rest/high-level/migration.asciidoc

@@ -64,7 +64,7 @@ argument:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-init]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-init]
 --------------------------------------------------
 
 NOTE: The `RestClient` uses Elasticsearch's HTTP service which is
@@ -91,7 +91,7 @@ must be replaced with:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[rest-high-level-client-close]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[rest-high-level-client-close]
 --------------------------------------------------
 
 === Changing the application's code
@@ -351,5 +351,3 @@ body, but any other JSON parser could have been use instead.
 
 We love to hear from you! Please give us your feedback about your migration
 experience and how to improve the Java High Level Rest Client on https://discuss.elastic.co/[our forum].
-
-

docs/java-rest/high-level/miscellaneous/main.asciidoc

@@ -8,7 +8,7 @@ Cluster information can be retrieved using the `info()` method:
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[main-execute]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[main-execute]
 --------------------------------------------------
 
 [[java-rest-high-main-response]]
@@ -18,7 +18,7 @@ The returned `MainResponse` provides various kinds of information about the clus
 
 ["source","java",subs="attributes,callouts,macros"]
 --------------------------------------------------
-include-tagged::{doc-tests}/MainDocumentationIT.java[main-response]
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[main-response]
 --------------------------------------------------
 <1> Retrieve the name of the cluster as a `ClusterName`
 <2> Retrieve the unique identifier of the cluster

docs/java-rest/high-level/miscellaneous/ping.asciidoc

@@ -0,0 +1,13 @@
+[[java-rest-high-ping]]
+=== Ping API
+
+[[java-rest-high-ping-request]]
+==== Execution
+
+The `ping()` method checks if the cluster is up and available to
+process requests and returns a boolean:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/MiscellaneousDocumentationIT.java[ping-execute]
+--------------------------------------------------

docs/java-rest/high-level/supported-apis.asciidoc

@@ -37,8 +37,10 @@ include::search/scroll.asciidoc[]
 The Java High Level REST Client supports the following Miscellaneous APIs:
 
 * <<java-rest-high-main>>
+* <<java-rest-high-ping>>
 
 include::miscellaneous/main.asciidoc[]
+include::miscellaneous/ping.asciidoc[]
 
 == Indices APIs