diff --git a/client/src/main/java/org/elasticsearch/client/DeadHostState.java b/client/src/main/java/org/elasticsearch/client/DeadHostState.java
index 44b7532d5de..a7b222da70e 100644
--- a/client/src/main/java/org/elasticsearch/client/DeadHostState.java
+++ b/client/src/main/java/org/elasticsearch/client/DeadHostState.java
@@ -41,6 +41,11 @@ final class DeadHostState {
         this.deadUntilNanos = System.nanoTime() + MIN_CONNECTION_TIMEOUT_NANOS;
     }
 
+    /**
+     * We keep track of how many times a certain node fails consecutively. The higher that number is the longer we will wait
+     * to retry that same node again. Minimum is 1 minute (for a node the only failed once), maximum is 30 minutes (for a node
+     * that failed many consecutive times).
+     */
     DeadHostState(DeadHostState previousDeadHostState) {
         long timeoutNanos = (long)Math.min(MIN_CONNECTION_TIMEOUT_NANOS * 2 * Math.pow(2, previousDeadHostState.failedAttempts * 0.5 - 1),
                 MAX_CONNECTION_TIMEOUT_NANOS);
diff --git a/client/src/main/java/org/elasticsearch/client/RequestLogger.java b/client/src/main/java/org/elasticsearch/client/RequestLogger.java
index f1b406b5cf3..c08e0c69941 100644
--- a/client/src/main/java/org/elasticsearch/client/RequestLogger.java
+++ b/client/src/main/java/org/elasticsearch/client/RequestLogger.java
@@ -40,6 +40,8 @@ import java.nio.charset.StandardCharsets;
 /**
  * Helper class that exposes static methods to unify the way requests are logged.
  * Includes trace logging to log complete requests and responses in curl format.
+ * Useful for debugging, manually sending logged requests via curl and checking their responses.
+ * Trace logging is a feature that all the language clients provide.
  */
 final class RequestLogger {