Add comments

Author: gkiko10

databricks-sdk-java/src/main/java/com/databricks/sdk/mixin/JobsExt.java

@@ -20,21 +20,20 @@ public JobsExt(JobsService mock) {
    *
    * <p>Depending on the Jobs API version used under the hood, tasks or iteration runs retrieved by
    * the initial request may be truncated due to high cardinalities. Truncation can happen for job
-   * runs over 100 task runs, as well as ForEach task runs with over 100 iteration runs. To avoid
+   * runs with over 100 task runs, as well as ForEach task runs with over 100 iteration runs. To avoid
    * returning an incomplete {@code Run} object to the user, this method performs all the requests
    * required to collect all task/iteration runs into a single {@code Run} object.
    */
   @Override
   public Run getRun(GetRunRequest request) {
     Run run = super.getRun(request);
 
-    /*
-     * fetch all additional pages (if any) and accumulate the result in a single response
-     */
-
+    // When querying a Job run, a page token is returned when there are more than 100 tasks. No iterations are defined for a Job run. Therefore, the next page in the response only includes the next page of tasks.
+    // When querying a ForEach task run, a page token is returned when there are more than 100 iterations. Only a single task is returned, corresponding to the ForEach task itself. Therefore, the client only reads the iterations from the next page and not the tasks.
     Collection<RunTask> iterations = run.getIterations();
     boolean paginatingIterations = iterations != null && !iterations.isEmpty();
 
+    // runs/get response includes next_page_token as long as there are more pages to fetch.
     while (run.getNextPageToken() != null) {
       request.setPageToken(run.getNextPageToken());
       Run currRun = super.getRun(request);
@@ -50,6 +49,7 @@ public Run getRun(GetRunRequest request) {
         }
       }
 
+      // Each new page of runs/get response includes the next page of the job_clusters, job_parameters, and repair history.
       Collection<JobCluster> newClusters = currRun.getJobClusters();
       if (newClusters != null) {
         run.getJobClusters().addAll(newClusters);