Add missing JavaDoc

modules/random/src/main/java/org/stubit/random/RandomChoice.java

@@ -3,11 +3,24 @@
 import java.security.SecureRandom;
 import java.util.Collection;
 import java.util.Map;
+import java.util.Map.Entry;
 
+/**
+ * Randomly selects an element from a collection of choices.
+ */
 public class RandomChoice {
 
   private static final SecureRandom random = new SecureRandom();
 
+  private RandomChoice() {}
+
+  /**
+   * Randomly selects an element from the provided choices.
+   *
+   * @param choices an array of choices
+   * @return a randomly selected element from the provided choices
+   * @param <T> the type of the choices
+   */
   @SafeVarargs
   public static <T> T anyOf(T... choices) {
     int size = choices.length;
@@ -17,18 +30,33 @@ public static <T> T anyOf(T... choices) {
     return choices[random.nextInt(size)];
   }
 
-  public static <T> T anyOf(Collection<T> collection) {
-    int size = collection.size();
+  /**
+   * Randomly selects an element from the provided choices {@link Collection}.
+   *
+   * @param choices a {@link Collection} of choices
+   * @return a randomly selected element from the provided choices
+   * @param <T> the type of the choices
+   */
+  public static <T> T anyOf(Collection<T> choices) {
+    int size = choices.size();
     if (size == 0) {
       throw new IllegalArgumentException("No choices provided");
     }
-    return collection.stream()
+    return choices.stream()
         .skip(random.nextInt(size))
         .findFirst()
         .orElseThrow(() -> new RuntimeException("Should not happen"));
   }
 
-  public static <K, V> Map.Entry<K, V> anyOf(Map<K, V> map) {
-    return anyOf(map.entrySet());
+    /**
+     * Randomly selects an element from the provided choices {@link Map}.
+     *
+     * @param choices a {@link Map} of choices
+     * @return a randomly selected {@link Entry} from the provided choices
+     * @param <K> the type of the choices keys
+     * @param <V> the type of the choices values
+     */
+  public static <K, V> Entry<K, V> anyOf(Map<K, V> choices) {
+    return anyOf(choices.entrySet());
   }
 }

modules/random/src/main/java/org/stubit/random/RandomIntBuilder.java

@@ -2,6 +2,9 @@
 
 import java.security.SecureRandom;
 
+/**
+ * Builds a random integer within a specified range.
+ */
 public class RandomIntBuilder {
 
   private final SecureRandom secureRandom = new SecureRandom();
@@ -13,18 +16,31 @@ private RandomIntBuilder(int min, int max) {
     this.max = max;
   }
 
+  /**
+   * @return a random integer between 1 and {@link Integer#MAX_VALUE}
+   */
   public static RandomIntBuilder aPositiveInt() {
     return new RandomIntBuilder(1, Integer.MAX_VALUE);
   }
 
+  /**
+   * @return a random integer between {@link Integer#MIN_VALUE} and -1
+   */
   public static RandomIntBuilder aNegativeInt() {
     return new RandomIntBuilder(Integer.MIN_VALUE, -1);
   }
 
+  /**
+   * @return a random integer between {@link Integer#MIN_VALUE} and {@link Integer#MAX_VALUE}
+   */
   public static RandomIntBuilder anInt() {
     return new RandomIntBuilder(Integer.MIN_VALUE, Integer.MAX_VALUE);
   }
 
+  /**
+   * @param min the minimum value (inclusive)
+   * @return this
+   */
   public RandomIntBuilder min(int min) {
     this.min = min;
     if (max <= min) {
@@ -33,6 +49,10 @@ public RandomIntBuilder min(int min) {
     return this;
   }
 
+  /**
+   * @param max the maximum value (exclusive)
+   * @return this
+   */
   public RandomIntBuilder max(int max) {
     this.max = max;
     if (min >= max) {
@@ -41,6 +61,9 @@ public RandomIntBuilder max(int max) {
     return this;
   }
 
+  /**
+   * @return a random integer between {@link #min} (inclusive) and {@link #max} (exclusive)
+   */
   public int build() {
     return secureRandom.nextInt(min, max);
   }