Update Inconsistent Javadoc (jgrapht#1224)

* Update existing Javadoc

- Add undocumented exception conditions
- Cleanup Javadoc syntax

* Update Javadoc for NotDirectedAcyclicGraphException

* Correctly document CrossComponentIterator behavior

Ref: jgrapht#1223

* Clarify exception for CrossComponentIterator

* Update graph iterator Javadoc

* Move exception description

* Add missing exception description

* Document exceptions for Guava adapters

jgrapht-core/src/main/java/org/jgrapht/Graph.java

@@ -117,6 +117,8 @@ public interface Graph<V, E>
      * {@link IllegalArgumentException} when calling method {@link Graph#addVertex()}.
      * 
      * @return the vertex supplier or {@code null} if the graph has no such supplier
+     * 
+     * @throws UnsupportedOperationException if this graph disallows access to the vertex supplier
      */
     Supplier<V> getVertexSupplier();
 
@@ -136,6 +138,8 @@ public interface Graph<V, E>
      * graph must not contain any edge {@code e2} such that {@code e2.equals(e)}.
      * 
      * @return the edge supplier {@code null} if the graph has no such supplier
+     * 
+     * @throws UnsupportedOperationException if this graph disallows access to the edge supplier
      */
     Supplier<E> getEdgeSupplier();
 
@@ -574,6 +578,7 @@ public interface Graph<V, E>
      * @param e edge of interest
      * @return edge weight
      * 
+     * @throws IllegalArgumentException if the specified edge is not in this graph
      * @throws NullPointerException if argument is {@code null}
      */
     double getEdgeWeight(E e);
@@ -593,15 +598,17 @@ public interface Graph<V, E>
 
     /**
      * Assigns a weight to an edge between {@code sourceVertex} and {@code targetVertex}.
-     * If no edge exists between {@code sourceVertex} and {@code targetVertex} or either
-     * of these vertices is {@code null}, a {@code NullPointerException} is thrown.
      * <p>
      * When there exist multiple edges between {@code sourceVertex} and
      * {@code targetVertex}, consider using {@link #setEdgeWeight(Object, double)} instead.
      *
      * @param sourceVertex source vertex of the edge
      * @param targetVertex target vertex of the edge
      * @param weight new weight for edge
+     * 
+     * @throws NullPointerException if either one of {@code sourceVertex} or
+     *                              {@code targetVertex} is {@code null}, or
+     *                              if there is no edge between the two vertices
      * @throws UnsupportedOperationException if the graph does not support weights
      */
     default void setEdgeWeight(V sourceVertex, V targetVertex, double weight)

jgrapht-core/src/main/java/org/jgrapht/alg/util/AliasMethodSampler.java

@@ -44,7 +44,8 @@ public class AliasMethodSampler
      * Constructor
      * 
      * @param p the probability distribution where position i of the array is $Prob(X=i)$
-     * @throws IllegalArgumentException in case of a non-valid probability distribution
+     * 
+     * @throws IllegalArgumentException if an invalid probability distribution is supplied
      */
     public AliasMethodSampler(double[] p)
     {
@@ -56,6 +57,9 @@ public AliasMethodSampler(double[] p)
      * 
      * @param p the probability distribution where position $i$ of the array is $Prob(X=i)$
      * @param seed seed to use for the random number generator
+     * 
+     * @throws IllegalArgumentException if an invalid probability distribution is supplied
+     * @throws NullPointerException if {@code rng} is {@code null}
      */
     public AliasMethodSampler(double[] p, long seed)
     {
@@ -67,7 +71,9 @@ public AliasMethodSampler(double[] p, long seed)
      * 
      * @param p the probability distribution where position $i$ of the array is $Prob(X=i)$
      * @param rng the random number generator
-     * @throws IllegalArgumentException in case of a non-valid probability distribution
+     * 
+     * @throws IllegalArgumentException if an invalid probability distribution is supplied
+     * @throws NullPointerException if {@code rng} is {@code null}
      */
     public AliasMethodSampler(double[] p, Random rng)
     {
@@ -80,7 +86,9 @@ public AliasMethodSampler(double[] p, Random rng)
      * @param p the probability distribution where position $i$ of the array is $Prob(X=i)$
      * @param rng the random number generator
      * @param epsilon tolerance used when comparing floating-point values
-     * @throws IllegalArgumentException in case of a non-valid probability distribution
+     * 
+     * @throws IllegalArgumentException if an invalid probability distribution is supplied
+     * @throws NullPointerException if {@code rng} is {@code null}
      */
     public AliasMethodSampler(double[] p, Random rng, double epsilon)
     {

jgrapht-core/src/main/java/org/jgrapht/alg/util/FixedSizeIntegerQueue.java

@@ -18,9 +18,11 @@
 package org.jgrapht.alg.util;
 
 /**
- * Primitive but efficient implementation of a fixed size queue for integers. Note: this queue is
- * not implemented as a ring, so at most $N$ enqueue operations are allowed, where $N$ is the
- * maximum capacity of the queue! After that, queue.clear() must be invoked.
+ * Primitive but efficient implementation of a fixed size queue for integers.
+ * 
+ * Note: this queue is not implemented as a ring, so at most $N$ enqueue
+ * operations are allowed, where $N$ is the maximum capacity of the queue!
+ * After that, {@link #clear()} must be invoked.
  *
  * @author Joris Kinable
  */

jgrapht-core/src/main/java/org/jgrapht/alg/util/NeighborCache.java

@@ -52,7 +52,7 @@ public class NeighborCache<V, E>
      * Constructor
      * 
      * @param graph the input graph
-     * @throws NullPointerException if the input graph is null
+     * @throws NullPointerException if the input graph is {@code null}
      */
     public NeighborCache(Graph<V, E> graph)
     {

jgrapht-core/src/main/java/org/jgrapht/alg/util/ToleranceDoubleComparator.java

@@ -65,6 +65,8 @@ public ToleranceDoubleComparator(double epsilon)
      * @param o1 the first value
      * @param o2 the second value
      * @return 0 if they are equal, -1 if {@literal o1 < o2}, 1 otherwise
+     * 
+     * @throws NullPointerException if either one of the arguments is {@code null}
      */
     @Override
     public int compare(Double o1, Double o2)

jgrapht-core/src/main/java/org/jgrapht/graph/AbstractBaseGraph.java

@@ -91,8 +91,8 @@ public abstract class AbstractBaseGraph<V, E>
     /**
      * Construct a new graph.
      *
-     * @param vertexSupplier the vertex supplier, can be null
-     * @param edgeSupplier the edge supplier, can be null
+     * @param vertexSupplier the vertex supplier, can be {@code null}
+     * @param edgeSupplier the edge supplier, can be {@code null}
      * @param type the graph type
      *
      * @throws IllegalArgumentException if the graph type is mixed
@@ -106,12 +106,15 @@ protected AbstractBaseGraph(
     /**
      * Construct a new graph.
      *
-     * @param vertexSupplier the vertex supplier, can be null
-     * @param edgeSupplier the edge supplier, can be null
+     * @param vertexSupplier the vertex supplier, can be {@code null}
+     * @param edgeSupplier the edge supplier, can be {@code null}
      * @param type the graph type
      * @param graphSpecificsStrategy strategy for constructing low-level graph specifics
      *
      * @throws IllegalArgumentException if the graph type is mixed
+     * @throws NullPointerException if either one of {@code type} or {@code graphSpecificsStragegy}
+     *                              is {@code null}, or if {@code graphSpecificsStragegy} generates
+     *                              {@code null}
      */
     protected AbstractBaseGraph(
         Supplier<V> vertexSupplier, Supplier<E> edgeSupplier, GraphType type,

jgrapht-core/src/main/java/org/jgrapht/graph/AsGraphUnion.java

@@ -60,6 +60,7 @@ public class AsGraphUnion<V, E>
      * @param g2 the second graph
      * @param operator the weight combiner (policy for edge weight calculation)
      * 
+     * @throws IllegalArgumentException if {@code g1 == g2}
      * @throws NullPointerException if any of the arguments is {@code null}
      */
     public AsGraphUnion(Graph<V, E> g1, Graph<V, E> g2, WeightCombiner operator)
@@ -96,6 +97,7 @@ public AsGraphUnion(Graph<V, E> g1, Graph<V, E> g2, WeightCombiner operator)
      * @param g1 the first graph
      * @param g2 the second graph
      * 
+     * @throws IllegalArgumentException if {@code g1 == g2}
      * @throws NullPointerException if any of the arguments is {@code null}
      */
     public AsGraphUnion(Graph<V, E> g1, Graph<V, E> g2)
@@ -234,7 +236,7 @@ public Set<E> edgeSet()
     }
 
     /**
-     * {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
      */
     @Override
     public Set<E> edgesOf(V vertex)
@@ -254,7 +256,7 @@ public Set<E> edgesOf(V vertex)
     }
 
     /**
-     * {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
      */
     @Override
     public Set<E> incomingEdgesOf(V vertex)
@@ -276,6 +278,8 @@ public Set<E> incomingEdgesOf(V vertex)
 
     /**
      * {@inheritDoc}
+     * 
+     * @throws IllegalArgumentException {@inheritDoc}
      */
     @Override
     public Set<E> outgoingEdgesOf(V vertex)
@@ -443,7 +447,7 @@ public V getEdgeTarget(E e)
     }
 
     /**
-     * {@inheritDoc}
+     * @throws IllegalArgumentException {@inheritDoc}
      */
     @Override
     public double getEdgeWeight(E e)
@@ -460,17 +464,14 @@ public double getEdgeWeight(E e)
         throw new IllegalArgumentException("no such edge in the union");
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
     public GraphType getType()
     {
         return type;
     }
 
     /**
-     * Throws {@link UnsupportedOperationException} since graph union is read-only.
+     * @throws UnsupportedOperationException always
      */
     @Override
     public void setEdgeWeight(E e, double weight)

jgrapht-core/src/main/java/org/jgrapht/graph/DefaultEdgeFunction.java

@@ -41,6 +41,8 @@ public class DefaultEdgeFunction<E, T>
      * Create a new function
      * 
      * @param defaultValue the default value
+     * 
+     * @throws NullPointerException if argument is {@code null}
      */
     public DefaultEdgeFunction(T defaultValue)
     {
@@ -52,6 +54,8 @@ public DefaultEdgeFunction(T defaultValue)
      * 
      * @param defaultValue the default value
      * @param map the underlying map
+     * 
+     * @throws NullPointerException if either one of the arguments is {@code null}
      */
     public DefaultEdgeFunction(T defaultValue, Map<E, T> map)
     {

jgrapht-core/src/main/java/org/jgrapht/graph/DefaultListenableGraph.java

@@ -57,6 +57,9 @@ public class DefaultListenableGraph<V, E>
      * Creates a new listenable graph.
      *
      * @param g the backing graph.
+     * 
+     * @throws IllegalArgumentException if the backing graph is already a listenable graph.
+     * @throws NullPointerException if {@code g} is {@code null}
      */
     public DefaultListenableGraph(Graph<V, E> g)
     {
@@ -74,6 +77,7 @@ public DefaultListenableGraph(Graph<V, E> g)
      *        event object for each event.
      *
      * @throws IllegalArgumentException if the backing graph is already a listenable graph.
+     * @throws NullPointerException if {@code g} is {@code null}
      */
     public DefaultListenableGraph(Graph<V, E> g, boolean reuseEvents)
     {

jgrapht-core/src/main/java/org/jgrapht/graph/GraphDelegator.java

@@ -57,16 +57,19 @@ public class GraphDelegator<V, E>
     private final Supplier<E> edgeSupplier;
 
     /**
-     * Constructor
+     * Constructs a new {@code GraphDelegator}.
      *
      * @param graph the backing graph (the delegate).
+     * 
+     * @throws NullPointerException if argument is {@code null}
      */
     public GraphDelegator(Graph<V, E> graph)
     {
         this(graph, null, null);
     }
 
     /**
+     * Constructs a new {@code GraphDelegator}.
      * 
      * @param graph the backing graph (the delegate).
      * @param vertexSupplier vertex supplier for the delegator. Can be null in which case the
@@ -85,11 +88,8 @@ public GraphDelegator(Graph<V, E> graph, Supplier<V> vertexSupplier, Supplier<E>
     }
 
     /**
-     * {@inheritDoc}
-     * 
-     * <p>
-     * Returns the delegator's vertex supplier or the backing graph's vertex supplier in case of
-     * null.
+     * @return the vertex supplier of this delegator or the backing graph's
+     *         vertex supplier if this delegator does not have a vertex supplier
      */
     @Override
     public Supplier<V> getVertexSupplier()
@@ -102,10 +102,8 @@ public Supplier<V> getVertexSupplier()
     }
 
     /**
-     * {@inheritDoc}
-     * 
-     * <p>
-     * Returns the delegator's edge supplier or the backing graph's edge supplier in case of null.
+     * @return the edge supplier of this delegator or the backing graph's
+     *         edge supplier if this delegator does not have an edge supplier
      */
     @Override
     public Supplier<E> getEdgeSupplier()

jgrapht-core/src/main/java/org/jgrapht/traverse/AbstractGraphIterator.java

@@ -51,6 +51,8 @@ public abstract class AbstractGraphIterator<V, E>
      * Create a new iterator
      * 
      * @param graph the graph
+     * 
+     * @throws NullPointerException if argument is {@code null}
      */
     public AbstractGraphIterator(Graph<V, E> graph)
     {
@@ -76,6 +78,8 @@ public Graph<V, E> getGraph()
      * connected components.
      *
      * @param crossComponentTraversal if {@code true} traverses across connected components.
+     * 
+     * @throws IllegalArgumentException if the argument is invalid for this iterator
      */
     public void setCrossComponentTraversal(boolean crossComponentTraversal)
     {
@@ -113,6 +117,9 @@ public void addTraversalListener(TraversalListener<V, E> l)
         nListeners = traversalListeners.size();
     }
 
+    /**
+     * @throws UnsupportedOperationException {@inheritDoc}
+     */
     @Override
     public void remove()
     {

jgrapht-core/src/main/java/org/jgrapht/traverse/BreadthFirstIterator.java

@@ -43,6 +43,8 @@ public class BreadthFirstIterator<V, E>
      * Creates a new breadth-first iterator for the specified graph.
      *
      * @param g the graph to be iterated.
+     * 
+     * @throws NullPointerException if argument is {@code null}
      */
     public BreadthFirstIterator(Graph<V, E> g)
     {