From da9d85e427e148c45b7a7533f01b8ec5279305a4 Mon Sep 17 00:00:00 2001
From: Hannes Greule <hannesgreule@outlook.de>
Date: Sat, 15 Aug 2020 18:05:26 +0200
Subject: [PATCH] Point out API usage of RandomCollection

---
 .../object/collection/FastRandomCollection.java  |  4 ++++
 .../fawe/object/collection/RandomCollection.java | 16 ++++++++++++++++
 .../collection/SimpleRandomCollection.java       |  8 ++++++++
 3 files changed, 28 insertions(+)

diff --git a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/FastRandomCollection.java b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/FastRandomCollection.java
index 6b68e9191..d283cfb57 100644
--- a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/FastRandomCollection.java
+++ b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/FastRandomCollection.java
@@ -17,11 +17,15 @@ public class FastRandomCollection<T> extends RandomCollection<T> {
 
     /**
      * Create a new FastRandomCollection if the given values and weights match the criteria.
+     * The criteria may change at any point, so this method isn't guaranteed to return a
+     * non-empty Optional in any case.
+     *
      * @param weights the weight of the values.
      * @param random the random generator to use for this collection.
      * @param <T> the value type.
      * @return an {@link Optional} containing the new collection if it could
      * be created, {@link Optional#empty()} otherwise.
+     * @see RandomCollection for API usage.
      */
     public static <T> Optional<RandomCollection<T>> create(Map<T, Double> weights, SimpleRandom random) {
         int max = 0;
diff --git a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/RandomCollection.java b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/RandomCollection.java
index b847b476a..ea83647bf 100644
--- a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/RandomCollection.java
+++ b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/RandomCollection.java
@@ -6,6 +6,13 @@ import java.util.Map;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
+/**
+ * A RandomCollection holds multiple values that can be accessed by using
+ * {@link RandomCollection#next(int, int, int)}. The returned value is
+ * determined by a given {@link SimpleRandom} implementation.
+ *
+ * @param <T> the type of values the collection holds.
+ */
 public abstract class RandomCollection<T> {
     private SimpleRandom random;
 
@@ -13,6 +20,15 @@ public abstract class RandomCollection<T> {
         this.random = random;
     }
 
+    /**
+     * Return a new RandomCollection. The implementation may differ depending on the
+     * given arguments but there is no need to differ.
+     *
+     * @param weights the weighted map.
+     * @param random  the random number generator.
+     * @param <T>     the type the collection holds.
+     * @return a RandomCollection using the given weights and the RNG.
+     */
     public static <T> RandomCollection<T> of(Map<T, Double> weights, SimpleRandom random) {
         checkNotNull(random);
         return FastRandomCollection.create(weights, random)
diff --git a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/SimpleRandomCollection.java b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/SimpleRandomCollection.java
index a5ddcde42..b3f7cdd76 100644
--- a/worldedit-core/src/main/java/com/boydti/fawe/object/collection/SimpleRandomCollection.java
+++ b/worldedit-core/src/main/java/com/boydti/fawe/object/collection/SimpleRandomCollection.java
@@ -11,6 +11,14 @@ public class SimpleRandomCollection<E> extends RandomCollection<E> {
     private final NavigableMap<Double, E> map = new TreeMap<>();
     private double total = 0;
 
+    /**
+     * Create a {@link RandomCollection} from a weighted map and a RNG.
+     * It is recommended to use {@link RandomCollection#of(Map, SimpleRandom)}
+     * instead of this constructor.
+     *
+     * @param weights the weighted map.
+     * @param random  the random number generator.
+     */
     public SimpleRandomCollection(Map<E, Double> weights, SimpleRandom random) {
         super(random);
         for (Map.Entry<E, Double> entry : weights.entrySet()) {