added comments on statistics in WriteAck

Author: zinal

topic/src/main/java/tech/ydb/topic/write/WriteAck.java

@@ -41,7 +41,10 @@ public Details getDetails() {
     }
 
     /**
-     * Obtain message write statistics
+     * Returns write statistics associated with this write confirmation.
+     * Note: The statistics may cover multiple messages confirmed together by the server.
+     * Although this WriteAck corresponds to a single written message, the server may confirm several messages in a single response.
+     * Therefore, the returned statistics may represent the combined data for all messages included in the same write confirmation from the server.
      * @return {@link Statistics} with timings if statistics are available or null otherwise
      */
     public Statistics getStatistics() {
@@ -60,13 +63,27 @@ public long getOffset() {
         }
     }
 
+    /**
+     * Messages batch statistics.
+     * All messages within the batch are persisted together so write
+     * statistics is for the whole messages batch.
+     */
     public static class Statistics {
         private final Duration persistingTime;
         private final Duration partitionQuotaWaitTime;
         private final Duration topicQuotaWaitTime;
         private final Duration maxQueueWaitTime;
         private final Duration minQueueWaitTime;
 
+        /**
+         * Create the messages batch statistics object, for a single messages batch.
+         * 
+         * @param persistingTime
+         * @param partitionQuotaWaitTime
+         * @param topicQuotaWaitTime
+         * @param maxQueueWaitTime
+         * @param minQueueWaitTime 
+         */
         public Statistics(Duration persistingTime,
                 Duration partitionQuotaWaitTime, Duration topicQuotaWaitTime,
                 Duration maxQueueWaitTime, Duration minQueueWaitTime) {
@@ -77,22 +94,37 @@ public Statistics(Duration persistingTime,
             this.minQueueWaitTime = minQueueWaitTime;
         }
 
+        /**
+         * @return Time spent in persisting of data.
+         */
         public Duration getPersistingTime() {
             return persistingTime;
         }
 
+        /**
+         * @return Time spent awaiting for partition write quota.
+         */
         public Duration getPartitionQuotaWaitTime() {
             return partitionQuotaWaitTime;
         }
 
+        /**
+         * @return Time spent awaiting for topic write quota.
+         */
         public Duration getTopicQuotaWaitTime() {
             return topicQuotaWaitTime;
         }
 
+        /**
+         * @return Time spent in queue before persisting, maximal of all messages in response.
+         */
         public Duration getMaxQueueWaitTime() {
             return maxQueueWaitTime;
         }
 
+        /**
+         * @return Time spent in queue before persisting, minimal of all messages in response.
+         */
         public Duration getMinQueueWaitTime() {
             return minQueueWaitTime;
         }