Add StreamOverflowException details

src/main/java/gr/james/sampling/ChaoSampling.java

@@ -8,6 +8,9 @@
  * According to this algorithm, the probability of an item to be in the final sample is proportional to its relative
  * weight. Weights are the range (0,+Inf), otherwise an {@link IllegalWeightException} is thrown.
  * <p>
+ * This implementation throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} are feeded or if the
+ * sum of the weights of the items feeded is {@link Double#POSITIVE_INFINITY}, whichever occurs first.
+ * <p>
  * The space complexity of this class is {@code O(k)}, where {@code k} is the sample size.
  *
  * @param <T> the item type

src/main/java/gr/james/sampling/EfraimidisSampling.java

@@ -9,6 +9,8 @@
  * explicit or implicit item selections of the sampling procedure. Weights are the range (0,+Inf), otherwise an
  * {@link IllegalWeightException} is thrown.
  * <p>
+ * This implementation never throws {@link StreamOverflowException}.
+ * <p>
  * The space complexity of this class is {@code O(k)}, where {@code k} is the sample size.
  *
  * @param <T> the item type

src/main/java/gr/james/sampling/RandomSampling.java

@@ -21,6 +21,9 @@
  * contain duplicate elements. Furthermore, elements need not be immutable and the sampling process does not rely on the
  * elements' {@code hashCode()} and {@code equals()} methods.
  * <p>
+ * Implementations can throw {@link StreamOverflowException} if some overflow has occurred in the internal state of the
+ * algorithm that would otherwise prevent it from functioning properly, typically related to the stream size.
+ * <p>
  * Classes that implement this interface have a static method with signature
  * <pre><code>
  * public static &lt;E&gt; RandomSamplingCollector&lt;E&gt; collector(int sampleSize, Random random)

src/main/java/gr/james/sampling/VitterXSampling.java

@@ -10,6 +10,8 @@
  * algorithms to perform better by efficiently calculating the number of items that need to be skipped, while making
  * fewer calls to the RNG.
  * <p>
+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded.
+ * <p>
  * The space complexity of this class is {@code O(k)}, where {@code k} is the sample size.
  *
  * @param <T> the item type

src/main/java/gr/james/sampling/VitterZSampling.java

@@ -10,6 +10,8 @@
  * algorithms to perform better by efficiently calculating the number of items that need to be skipped, while making
  * fewer calls to the RNG.
  * <p>
+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded.
+ * <p>
  * The space complexity of this class is {@code O(k)}, where {@code k} is the sample size.
  *
  * @param <T> the item type

src/main/java/gr/james/sampling/WatermanSampling.java

@@ -11,6 +11,8 @@
  * {@link VitterXSampling} and {@link VitterZSampling} decide how many items to skip, rather than deciding whether or
  * not to skip an item each time it is feeded.
  * <p>
+ * This implementations throws {@link StreamOverflowException} if more than {@link Long#MAX_VALUE} items are feeded.
+ * <p>
  * The space complexity of this class is {@code O(k)}, where {@code k} is the sample size.
  *
  * @param <T> the item type

src/main/java/gr/james/sampling/WeightedRandomSampling.java

@@ -28,6 +28,9 @@
  * contain duplicate elements. Furthermore, elements need not be immutable and the sampling process does not rely on the
  * elements' {@code hashCode()} and {@code equals()} methods.
  * <p>
+ * Implementations can throw {@link StreamOverflowException} if some overflow has occurred in the internal state of the
+ * algorithm that would otherwise prevent it from functioning properly, typically related to the stream size.
+ * <p>
  * Classes that implement this interface have a static method with signature
  * <pre><code>
  * public static &lt;E&gt; WeightedRandomSamplingCollector&lt;E&gt; weightedCollector(int sampleSize, Random random)