From 82f286b4d1441cf15e32cc629c66b5c9caa0f286 Mon Sep 17 00:00:00 2001
From: M Sazzadul Hoque <7600764+sazzad16@users.noreply.github.com>
Date: Mon, 2 Jan 2023 15:17:56 +0600
Subject: [PATCH] Improved Transaction classes documentation (#3262)

* More info in docs of transaction classes

* Apply code reviews

* More docs

* Code comment
---
 .../clients/jedis/ReliableTransaction.java    | 22 +++++++++++++++++--
 .../java/redis/clients/jedis/Transaction.java | 19 +++++++++++++++-
 .../redis/clients/jedis/TransactionBase.java  | 14 +++++++++++-
 3 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/src/main/java/redis/clients/jedis/ReliableTransaction.java b/src/main/java/redis/clients/jedis/ReliableTransaction.java
index 911156757b..a2ffafc2e0 100644
--- a/src/main/java/redis/clients/jedis/ReliableTransaction.java
+++ b/src/main/java/redis/clients/jedis/ReliableTransaction.java
@@ -3,14 +3,32 @@
 import java.util.List;
 import redis.clients.jedis.exceptions.JedisException;
 
+/**
+ * ReliableTransaction is a transaction where commands are immediately sent to Redis server and the
+ * 'QUEUED' reply checked.
+ */
 public class ReliableTransaction extends TransactionBase {
 
+  private static final String QUEUED_STR = "QUEUED";
+
+  /**
+   * Creates a new transaction.
+   * 
+   * A MULTI command will be added to be sent to server. WATCH/UNWATCH/MULTI commands must not be
+   * called with this object.
+   */
   public ReliableTransaction(Connection connection) {
     super(connection);
   }
 
   /**
-   * If you want to WATCH/UNWATCH keys before MULTI command you should do {@code doMulti = true}.
+   * Creates a new transaction.
+   *
+   * A user wanting to WATCH/UNWATCH keys followed by a call to MULTI ({@link #multi()}) it should
+   * be {@code doMulti=false}.
+   *
+   * @param connection connection
+   * @param doMulti {@code false} should be set to enable manual WATCH, UNWATCH and MULTI
    */
   public ReliableTransaction(Connection connection, boolean doMulti) {
     super(connection, doMulti);
@@ -27,7 +45,7 @@ protected final void processMultiResponse() {
   @Override
   protected final void processAppendStatus() {
     String status = connection.getStatusCodeReply();
-    if (!"QUEUED".equals(status)) {
+    if (!QUEUED_STR.equals(status)) {
       throw new JedisException(status);
     }
   }
diff --git a/src/main/java/redis/clients/jedis/Transaction.java b/src/main/java/redis/clients/jedis/Transaction.java
index 278e5fd4bd..feb6f0af11 100644
--- a/src/main/java/redis/clients/jedis/Transaction.java
+++ b/src/main/java/redis/clients/jedis/Transaction.java
@@ -2,22 +2,39 @@
 
 import java.util.List;
 
+/**
+ * A pipeline based transaction.
+ */
 public class Transaction extends TransactionBase {
 
   private final Jedis jedis;
 
+  // Legacy - to support Jedis.multi()
+  // TODO: Should be package private ??
   public Transaction(Jedis jedis) {
     super(jedis.getConnection());
     this.jedis = jedis;
   }
 
+  /**
+   * Creates a new transaction.
+   * 
+   * A MULTI command will be added to be sent to server. WATCH/UNWATCH/MULTI commands must not be
+   * called with this object.
+   */
   public Transaction(Connection connection) {
     super(connection);
     this.jedis = null;
   }
 
   /**
-   * If you want to WATCH/UNWATCH keys before MULTI command you should do {@code doMulti = true}.
+   * Creates a new transaction.
+   *
+   * A user wanting to WATCH/UNWATCH keys followed by a call to MULTI ({@link #multi()}) it should
+   * be {@code doMulti=false}.
+   *
+   * @param connection connection
+   * @param doMulti {@code false} should be set to enable manual WATCH, UNWATCH and MULTI
    */
   public Transaction(Connection connection, boolean doMulti) {
     super(connection, doMulti);
diff --git a/src/main/java/redis/clients/jedis/TransactionBase.java b/src/main/java/redis/clients/jedis/TransactionBase.java
index b63ddfc012..4d6cb6c16d 100644
--- a/src/main/java/redis/clients/jedis/TransactionBase.java
+++ b/src/main/java/redis/clients/jedis/TransactionBase.java
@@ -46,12 +46,24 @@ public abstract class TransactionBase extends Queable implements PipelineCommand
   private boolean inWatch = false;
   private boolean inMulti = false;
 
+  /**
+   * Creates a new transaction.
+   * 
+   * A MULTI command will be added to be sent to server. WATCH/UNWATCH/MULTI commands must not be
+   * called with this object.
+   */
   public TransactionBase(Connection connection) {
     this(connection, true);
   }
 
   /**
-   * If you want to WATCH/UNWATCH keys before MULTI command you should do {@code doMulti = true}.
+   * Creates a new transaction.
+   *
+   * A user wanting to WATCH/UNWATCH keys followed by a call to MULTI ({@link #multi()}) it should
+   * be {@code doMulti=false}.
+   *
+   * @param connection connection
+   * @param doMulti {@code false} should be set to enable manual WATCH, UNWATCH and MULTI
    */
   public TransactionBase(Connection connection, boolean doMulti) {
     this.connection = connection;