From a085134b56e6ba9c7b280add2c8326633e386ab5 Mon Sep 17 00:00:00 2001
From: Rob Rudin <rob.rudin@marklogic.com>
Date: Tue, 28 Mar 2023 14:24:51 -0400
Subject: [PATCH] DEVEXP-361 Improved javadocs for JobReport

---
 .../marklogic/client/datamovement/JobReport.java   | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/JobReport.java b/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/JobReport.java
index f9e02a711..69f7e4bcd 100644
--- a/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/JobReport.java
+++ b/marklogic-client-api/src/main/java/com/marklogic/client/datamovement/JobReport.java
@@ -21,29 +21,35 @@
  * A Job report is used to report status on a {@link WriteBatcher} or a {@link QueryBatcher}
  * job at any point of time after it is started and provide a
  * snapshot of the job's status at that time.
+ * <p>
+ * Note that for a query job, the counts of successful and failed events and batches only account for the process of
+ * retrieving items from the database. They do not account for the processing of batches of items via user-provided
+ * instances of {@link QueryBatchListener}. Such instances are responsible for determining their own definitions of
+ * "success" and "failure". See {@link ApplyTransformListener} for an example of how this can be done.
+ * </p>
  */
 public interface JobReport {
   /**
    * {@link WriteBatcher} : gets the number of documents written to the database<br>
-   * {@link QueryBatcher} : gets the number of uris processed from the database
+   * {@link QueryBatcher} : gets the number of items retrieved from the database
    * @return the number of events that succeeded
    */
   long getSuccessEventsCount();
   /**
    * {@link WriteBatcher} : gets the number of documents that were sent but failed to write<br>
-   * {@link QueryBatcher} : gets the number of batches that failed to process (same as getFailureBatchesCount)
+   * {@link QueryBatcher} : gets the number of batches that the job failed to retrieve (same as getFailureBatchesCount)
    * @return the number of events that failed
    */
   long getFailureEventsCount();
   /**
    * {@link WriteBatcher} : gets the number of batches written to the database<br>
-   * {@link QueryBatcher} : gets the number of batches processed from the database
+   * {@link QueryBatcher} : gets the number of batches retrieved from the database
    * @return the number of batches that succeeded
    */
   long getSuccessBatchesCount();
   /**
    * {@link WriteBatcher} : gets the number of batches that the job failed to write<br>
-   * {@link QueryBatcher} : gets the number of batches that failed to process (same as getFailureEventsCount)
+   * {@link QueryBatcher} : gets the number of batches that the job failed to retrieve (same as getFailureEventsCount)
    * @return the number of batches that failed
    */
   long getFailureBatchesCount();