add API doc for NullPointerExceptions

primitiveCollections/src/main/java/org/lucares/collections/IntList.java

@@ -70,6 +70,8 @@ public final class IntList implements Serializable, Cloneable {
 	 *
 	 * @param intList
 	 *            the list to copy
+	 * @throws NullPointerException
+	 *             if the specified {@link IntList} is null
 	 */
 	public IntList(final IntList intList) {
 		data = new int[intList.getCapacity()];
@@ -83,6 +85,8 @@ public final class IntList implements Serializable, Cloneable {
 	 * @param values
 	 *            the values
 	 * @return the list
+	 * @throws NullPointerException
+	 *             if the specified array is null
 	 */
 	public static IntList of(final int... values) {
 		final IntList result = new IntList(values.length);
@@ -142,7 +146,7 @@ public final class IntList implements Serializable, Cloneable {
 	 * @throws IndexOutOfBoundsException
 	 *             if pos is out of bounds {@code pos < 0 || pos > size()}
 	 * @throws NullPointerException
-	 *             if {@code values} is {@code null}
+	 *             if the given array is null
 	 */
 	public void insert(final int pos, final int... values) {
 
@@ -195,7 +199,7 @@ public final class IntList implements Serializable, Cloneable {
 	 * @param values
 	 *            the values to add
 	 * @throws NullPointerException
-	 *             if {@code values} is {@code null}
+	 *             if the given array is null
 	 */
 	public void addAll(final int... values) {
 		ensureCapacity(values.length);
@@ -229,7 +233,8 @@ public final class IntList implements Serializable, Cloneable {
 			throw new IndexOutOfBoundsException("toIndex must not be smaller than fromIndex, but was: " + toIndex);
 		}
 		if (toIndex > index) {
-			throw new IndexOutOfBoundsException("from: " + fromIndex + " toIndex: " + toIndex);
+			throw new IndexOutOfBoundsException(
+					"toIndex must not be larger than the size of this list, but was: " + toIndex);
 		}
 
 		final int numRemoved = index - toIndex;
@@ -246,6 +251,8 @@ public final class IntList implements Serializable, Cloneable {
 	 *
 	 * @param remove
 	 *            the elements to remove
+	 * @throws NullPointerException
+	 *             if the specified {@link IntList} is null
 	 * @see #trim()
 	 */
 	public void removeAll(final IntList remove) {
@@ -272,6 +279,8 @@ public final class IntList implements Serializable, Cloneable {
 	 *
 	 * @param predicate
 	 *            the predicate
+	 * @throws NullPointerException
+	 *             if the specified predicate is null
 	 * @see #trim()
 	 */
 	public void removeIf(final IntPredicate predicate) {
@@ -298,6 +307,8 @@ public final class IntList implements Serializable, Cloneable {
 	 *
 	 * @param retain
 	 *            the elements to retain
+	 * @throws NullPointerException
+	 *             if the specified {@link IntList} is null
 	 * @see #trim()
 	 */
 	public void retainAll(final IntList retain) {
@@ -319,6 +330,8 @@ public final class IntList implements Serializable, Cloneable {
 	 *
 	 * @param operator
 	 *            the operator
+	 * @throws NullPointerException
+	 *             if the specified {@link UnaryIntOperator} is null
 	 */
 	public void replaceAll(final UnaryIntOperator operator) {
 		final int size = index;
@@ -382,6 +395,15 @@ public final class IntList implements Serializable, Cloneable {
 		return get(0, index);
 	}
 
+	/**
+	 * Fills the given array with the elements of this list if the array can hold
+	 * all elements. A new array is returned otherwise.
+	 *
+	 * @param input
+	 * @throws NullPointerException
+	 *             if the specified array is null
+	 * @return an array containing all elements of this list
+	 */
 	public int[] toArray(final int[] input) {
 
 		if (input.length < index) {
@@ -398,6 +420,14 @@ public final class IntList implements Serializable, Cloneable {
 		Arrays.sort(data, 0, index);
 	}
 
+	/**
+	 * Sorts the list into ascending order using an algorithm than can use
+	 * parallelism.
+	 */
+	public void parallelSort() {
+		Arrays.parallelSort(data, 0, index);
+	}
+
 	private void ensureCapacity(final int newElements) {
 
 		final int requiredCapacity = index + newElements;