Improved Transaction classes documentation (#3262)

* More info in docs of transaction classes

* Apply code reviews

* More docs

* Code comment

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);
     }
   }

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);

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;