Add javadoc summary where missing

The javadoc summary is expected by error-prone's `MissingSummary` check.
Apparently the error-prone version currently in use could not find
these, but a newer version can.

flink/v1.17/flink/src/main/java/org/apache/iceberg/flink/sink/shuffle/MapRangePartitioner.java

@@ -163,6 +163,8 @@ Map<SortKey, Long> mapStatistics() {
   }
 
   /**
+   * Returns assignment summary for every subtask.
+   *
    * @return assignment summary for every subtask. Key is subtaskId. Value pair is (weight assigned
    *     to the subtask, number of keys assigned to the subtask)
    */
@@ -328,7 +330,11 @@ static class KeyAssignment {
       }
     }
 
-    /** @return subtask id */
+    /**
+     * Select a subtask for the key.
+     *
+     * @return subtask id
+     */
     int select() {
       if (assignedSubtasks.length == 1) {
         // only choice. no need to run random number generator.

flink/v1.17/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/EnumerationHistory.java

@@ -78,7 +78,11 @@ synchronized boolean hasFullHistory() {
     return count >= history.length;
   }
 
-  /** @return true if split discovery should pause because assigner has too many splits already. */
+  /**
+   * Checks whether split discovery should paused.
+   *
+   * @return true if split discovery should pause because assigner has too many splits already.
+   */
   synchronized boolean shouldPauseSplitDiscovery(int pendingSplitCountFromAssigner) {
     if (count < history.length) {
       // only check throttling when full history is obtained.

flink/v1.18/flink/src/main/java/org/apache/iceberg/flink/sink/shuffle/MapRangePartitioner.java

@@ -163,6 +163,8 @@ Map<SortKey, Long> mapStatistics() {
   }
 
   /**
+   * Returns assignment summary for every subtask.
+   *
    * @return assignment summary for every subtask. Key is subtaskId. Value pair is (weight assigned
    *     to the subtask, number of keys assigned to the subtask)
    */
@@ -328,7 +330,11 @@ static class KeyAssignment {
       }
     }
 
-    /** @return subtask id */
+    /**
+     * Select a subtask for the key.
+     *
+     * @return subtask id
+     */
     int select() {
       if (assignedSubtasks.length == 1) {
         // only choice. no need to run random number generator.

flink/v1.18/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/EnumerationHistory.java

@@ -78,7 +78,11 @@ synchronized boolean hasFullHistory() {
     return count >= history.length;
   }
 
-  /** @return true if split discovery should pause because assigner has too many splits already. */
+  /**
+   * Checks whether split discovery should paused.
+   *
+   * @return true if split discovery should pause because assigner has too many splits already.
+   */
   synchronized boolean shouldPauseSplitDiscovery(int pendingSplitCountFromAssigner) {
     if (count < history.length) {
       // only check throttling when full history is obtained.

flink/v1.19/flink/src/main/java/org/apache/iceberg/flink/sink/shuffle/MapRangePartitioner.java

@@ -161,6 +161,8 @@ Map<SortKey, Long> mapStatistics() {
   }
 
   /**
+   * Returns assignment summary for every subtask.
+   *
    * @return assignment summary for every subtask. Key is subtaskId. Value pair is (weight assigned
    *     to the subtask, number of keys assigned to the subtask)
    */
@@ -326,7 +328,11 @@ static class KeyAssignment {
       }
     }
 
-    /** @return subtask id */
+    /**
+     * Select a subtask for the key.
+     *
+     * @return subtask id
+     */
     int select() {
       if (assignedSubtasks.length == 1) {
         // only choice. no need to run random number generator.

flink/v1.19/flink/src/main/java/org/apache/iceberg/flink/source/enumerator/EnumerationHistory.java

@@ -78,7 +78,11 @@ synchronized boolean hasFullHistory() {
     return count >= history.length;
   }
 
-  /** @return true if split discovery should pause because assigner has too many splits already. */
+  /**
+   * Checks whether split discovery should paused.
+   *
+   * @return true if split discovery should pause because assigner has too many splits already.
+   */
   synchronized boolean shouldPauseSplitDiscovery(int pendingSplitCountFromAssigner) {
     if (count < history.length) {
       // only check throttling when full history is obtained.