From 5c4601584aa021b05e4f0c8c9cd8b013b5e1b847 Mon Sep 17 00:00:00 2001
From: SanHalacogluImproving
 <144171266+SanHalacogluImproving@users.noreply.github.com>
Date: Tue, 5 Mar 2024 12:19:35 -0800
Subject: [PATCH] Java: Add examples to missing commands and minor fixes
 Generic Commands. (#125) (#1070)

* Java: Add examples to missing commands and minor fixes. (#125)

* Minor documentation changes.

* Minor documentation changes.
---
 .../api/commands/GenericBaseCommands.java     | 91 ++++++++++---------
 .../api/commands/GenericClusterCommands.java  | 35 +++++--
 .../glide/api/commands/GenericCommands.java   | 12 +++
 3 files changed, 87 insertions(+), 51 deletions(-)

diff --git a/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java b/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java
index e7a47bf279..d8c29319aa 100644
--- a/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java
+++ b/java/client/src/main/java/glide/api/commands/GenericBaseCommands.java
@@ -18,6 +18,11 @@ public interface GenericBaseCommands {
      * @see <a href="https://redis.io/commands/del/">redis.io</a> for details.
      * @param keys The keys we wanted to remove.
      * @return The number of keys that were removed.
+     * @example
+     *     <pre>{@code
+     * Long num = client.del(new String[] {"key1", "key2"}).get();
+     * assert num == 2l;
+     * }</pre>
      */
     CompletableFuture<Long> del(String[] keys);
 
@@ -29,10 +34,10 @@ public interface GenericBaseCommands {
      * @return The number of keys that exist. If the same existing key is mentioned in <code>keys
      *     </code> multiple times, it will be counted multiple times.
      * @example
-     *     <p><code>
-     * long result = client.exists(new String[] {"my_key", "invalid_key"}).get();
+     *     <pre>{@code
+     * Long result = client.exists(new String[] {"my_key", "invalid_key"}).get();
      * assert result == 1L;
-     * </code>
+     * }</pre>
      */
     CompletableFuture<Long> exists(String[] keys);
 
@@ -46,11 +51,10 @@ public interface GenericBaseCommands {
      * @param keys The list of keys to unlink.
      * @return The number of <code>keys</code> that were unlinked.
      * @example
-     *     <p>
-     *     <pre>
-     * long result = client.unlink("my_key").get();
+     *     <pre>{@code
+     * Long result = client.unlink("my_key").get();
      * assert result == 1L;
-     * </pre>
+     * }</pre>
      */
     CompletableFuture<Long> unlink(String[] keys);
 
@@ -70,10 +74,10 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist.
      * @example
-     *     <pre>
-     * Boolean isSet = client.expire("my_key", 60).get()
-     * assert isSet //Indicates that a timeout of 60 seconds has been set for "my_key."
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.expire("my_key", 60).get();
+     * assert isSet; //Indicates that a timeout of 60 seconds has been set for "my_key."
+     * }</pre>
      */
     CompletableFuture<Boolean> expire(String key, long seconds);
 
@@ -95,10 +99,10 @@ public interface GenericBaseCommands {
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
      * @example
-     *     <pre>
-     * Boolean isSet = client.expire("my_key", 60, ExpireOptions.HAS_NO_EXPIRY).get()
-     * assert isSet //Indicates that a timeout of 60 seconds has been set for "my_key."
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.expire("my_key", 60, ExpireOptions.HAS_NO_EXPIRY).get();
+     * assert isSet; //Indicates that a timeout of 60 seconds has been set for "my_key."
+     * }</pre>
      */
     CompletableFuture<Boolean> expire(String key, long seconds, ExpireOptions expireOptions);
 
@@ -118,10 +122,10 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist.
      * @example
-     *     <pre>
-     * Boolean isSet = client.expireAt("my_key", Instant.now().getEpochSecond() + 10).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.expireAt("my_key", Instant.now().getEpochSecond() + 10).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> expireAt(String key, long unixSeconds);
 
@@ -143,10 +147,10 @@ public interface GenericBaseCommands {
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
      * @example
-     *     <pre>
-     * Boolean isSet = client.expireAt("my_key", Instant.now().getEpochSecond() + 10, ExpireOptions.HasNoExpiry).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.expireAt("my_key", Instant.now().getEpochSecond() + 10, ExpireOptions.HasNoExpiry).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> expireAt(String key, long unixSeconds, ExpireOptions expireOptions);
 
@@ -166,10 +170,10 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist.
      * @example
-     *     <pre>
-     * Boolean isSet = client.pexpire("my_key", 60000).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.pexpire("my_key", 60000).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> pexpire(String key, long milliseconds);
 
@@ -191,10 +195,10 @@ public interface GenericBaseCommands {
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
      * @example
-     *     <pre>
-     * Boolean isSet = client.pexpire("my_key", 60000, ExpireOptions.HasNoExpiry).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.pexpire("my_key", 60000, ExpireOptions.HasNoExpiry).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> pexpire(String key, long milliseconds, ExpireOptions expireOptions);
 
@@ -214,10 +218,10 @@ public interface GenericBaseCommands {
      * @return <code>true</code> if the timeout was set. <code>false</code> if the timeout was not
      *     set. e.g. <code>key</code> doesn't exist.
      * @example
-     *     <pre>
-     * Boolean isSet = client.pexpireAt("my_key", Instant.now().toEpochMilli() + 10).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.pexpireAt("my_key", Instant.now().toEpochMilli() + 10).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> pexpireAt(String key, long unixMilliseconds);
 
@@ -239,10 +243,10 @@ public interface GenericBaseCommands {
      *     set. e.g. <code>key</code> doesn't exist, or operation skipped due to the provided
      *     arguments.
      * @example
-     *     <pre>
-     * Boolean isSet = client.pexpireAt("my_key", Instant.now().toEpochMilli() + 10, ExpireOptions.HasNoExpiry).get()
-     * assert isSet
-     * </pre>
+     *     <pre>{@code
+     * Boolean isSet = client.pexpireAt("my_key", Instant.now().toEpochMilli() + 10, ExpireOptions.HasNoExpiry).get();
+     * assert isSet;
+     * }</pre>
      */
     CompletableFuture<Boolean> pexpireAt(
             String key, long unixMilliseconds, ExpireOptions expireOptions);
@@ -255,12 +259,13 @@ CompletableFuture<Boolean> pexpireAt(
      * @return TTL in seconds, <code>-2</code> if <code>key</code> does not exist, or <code>-1</code>
      *     if <code>key</code> exists but has no associated expire.
      * @example
-     *     <pre>
+     *     <pre>{@code
      * Long timeRemaining = client.ttl("my_key").get()
      * assert timeRemaining == 3600L //Indicates that "my_key" has a remaining time to live of 3600 seconds.
-     * Long timeRemaining = client.ttl("nonexistent_key").get()
-     * assert timeRemaining == -2L //Returns -2 for a non-existing key.
-     * </pre>
+     *
+     * Long timeRemaining = client.ttl("nonexistent_key").get();
+     * assert timeRemaining == -2L; //Returns -2 for a non-existing key.
+     * }</pre>
      */
     CompletableFuture<Long> ttl(String key);
 }
diff --git a/java/client/src/main/java/glide/api/commands/GenericClusterCommands.java b/java/client/src/main/java/glide/api/commands/GenericClusterCommands.java
index 1fbca154cc..95e56335d6 100644
--- a/java/client/src/main/java/glide/api/commands/GenericClusterCommands.java
+++ b/java/client/src/main/java/glide/api/commands/GenericClusterCommands.java
@@ -26,12 +26,13 @@ public interface GenericClusterCommands {
      *     response (such as <em>XREAD</em>), or that change the client's behavior (such as entering
      *     <em>pub</em>/<em>sub</em> mode on <em>RESP2</em> connections) shouldn't be called using
      *     this function.
-     * @example Returns a list of all <em>pub</em>/<em>sub</em> clients:
-     *     <p><code>
-     * Object result = client.customCommand(new String[]{ "CLIENT", "LIST", "TYPE", "PUBSUB" }).get();
-     * </code>
      * @param args Arguments for the custom command including the command name.
      * @return Response from Redis containing an <code>Object</code>.
+     * @example
+     *     <pre>{@code
+     * ClusterValue<Object> data = client.customCommand(new String[] {"ping"}).get();
+     * assert ((String) data.getSingleValue()).equals("PONG");
+     * }</pre>
      */
     CompletableFuture<ClusterValue<Object>> customCommand(String[] args);
 
@@ -46,13 +47,16 @@ public interface GenericClusterCommands {
      *     response (such as <em>XREAD</em>), or that change the client's behavior (such as entering
      *     <em>pub</em>/<em>sub</em> mode on <em>RESP2</em> connections) shouldn't be called using
      *     this function.
-     * @example Returns a list of all <em>pub</em>/<em>sub</em> clients:
-     *     <p><code>
-     * Object result = client.customCommand(new String[]{ "CLIENT", "LIST", "TYPE", "PUBSUB" }, RANDOM).get();
-     * </code>
      * @param args Arguments for the custom command including the command name
      * @param route Routing configuration for the command
      * @return Response from Redis containing an <code>Object</code>.
+     * @example
+     *     <pre>{@code
+     * ClusterValue<Object> result = clusterClient.customCommand(new String[]{ "CONFIG", "GET", "maxmemory"}, ALL_NODES).get();
+     * Map<String, Object> payload = result.getMultiValue();
+     * assert ((String) payload.get("node1")).equals("1GB");
+     * assert ((String) payload.get("node2")).equals("100MB");
+     * }</pre>
      */
     CompletableFuture<ClusterValue<Object>> customCommand(String[] args, Route route);
 
@@ -73,6 +77,13 @@ public interface GenericClusterCommands {
      *       <li>If the transaction failed due to a <code>WATCH</code> command, <code>exec</code> will
      *           return <code>null</code>.
      *     </ul>
+     *
+     * @example
+     *     <pre>{@code
+     * ClusterTransaction transaction = new ClusterTransaction().customCommand(new String[] {"info"});
+     * Object[] result = clusterClient.exec(transaction).get();
+     * assert ((String) result[0]).contains("# Stats");
+     * }</pre>
      */
     CompletableFuture<Object[]> exec(ClusterTransaction transaction);
 
@@ -92,6 +103,14 @@ public interface GenericClusterCommands {
      *       <li>If the transaction failed due to a <code>WATCH</code> command, <code>exec</code> will
      *           return <code>null</code>.
      *     </ul>
+     *
+     * @example
+     *     <pre>{@code
+     * ClusterTransaction transaction = new ClusterTransaction().ping().info();
+     * ClusterValue<Object>[] result = clusterClient.exec(transaction, RANDOM).get();
+     * assert ((String) result[0].getSingleValue()).equals("PONG");
+     * assert ((String) result[1].getSingleValue()).contains("# Stats");
+     * }</pre>
      */
     CompletableFuture<ClusterValue<Object>[]> exec(ClusterTransaction transaction, Route route);
 }
diff --git a/java/client/src/main/java/glide/api/commands/GenericCommands.java b/java/client/src/main/java/glide/api/commands/GenericCommands.java
index 126188457f..d76a7f4f7b 100644
--- a/java/client/src/main/java/glide/api/commands/GenericCommands.java
+++ b/java/client/src/main/java/glide/api/commands/GenericCommands.java
@@ -28,6 +28,11 @@ public interface GenericCommands {
      *
      * @param args Arguments for the custom command.
      * @return Response from Redis containing an <code>Object</code>.
+     * @example
+     *     <pre>{@code
+     * Object response = (String) client.customCommand(new String[] {"ping", "GLIDE"}).get()
+     * assert ((String) response).equals("GLIDE");
+     * }</pre>
      */
     CompletableFuture<Object> customCommand(String[] args);
 
@@ -45,6 +50,13 @@ public interface GenericCommands {
      *       <li>If the transaction failed due to a <code>WATCH</code> command, <code>exec</code> will
      *           return <code>null</code>.
      *     </ul>
+     *
+     * @example
+     *     <pre>{@code
+     * Transaction transaction = new Transaction().customCommand(new String[] {"info"});
+     * Object[] result = client.exec(transaction).get();
+     * assert ((String) result[0]).contains("# Stats");
+     * }</pre>
      */
     CompletableFuture<Object[]> exec(Transaction transaction);
 }