Point out API usage of RandomCollection

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;

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)

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()) {