Cleanup reported javadoc warnings (#72)

* initial fixes of non-generated javadoc

* exclude ParseExceptions from javadocs

* add missing throws doc

api/src/main/java/net/automatalib/alphabet/GrowingAlphabet.java

@@ -27,6 +27,9 @@ public interface GrowingAlphabet<I> extends Alphabet<I> {
      * Adds a new symbol to the alphabet. Some alphabets may prevent symbols from being added twice. In this case, the
      * original alphabet remains unchanged, but this is not considered an error.
      *
+     * @param a
+     *         the symbol to add
+     *
      * @return the index of the symbol in the alphabet, after adding it.
      */
     int addSymbol(I a);

api/src/main/java/net/automatalib/automaton/MutableAutomaton.java

@@ -45,19 +45,42 @@ public interface MutableAutomaton<S, I, T, SP, TP> extends UniversalAutomaton<S,
      */
     void clear();
 
+    /**
+     * Adds a new state (with an empty property) to the automaton.
+     *
+     * @return the newly created state
+     */
     default S addState() {
         return addState(null);
     }
 
     /**
-     * Adds a state to the automaton.
+     * Adds a new state with the given property to the automaton.
+     *
+     * @param property
+     *         the property of the new state
+     *
+     * @return the newly created state
      */
     S addState(@Nullable SP property);
 
+    /**
+     * Adds an initial state (with an empty property) to the automaton.
+     *
+     * @return the newly created state
+     */
     default S addInitialState() {
         return addInitialState(null);
     }
 
+    /**
+     * Adds an initial state with the given property to the automaton.
+     *
+     * @param property
+     *         the property of the new state
+     *
+     * @return the newly created state
+     */
     default S addInitialState(@Nullable SP property) {
         S state = addState(property);
         setInitial(state, true);

api/src/main/java/net/automatalib/graph/BidirectionalGraph.java

@@ -34,7 +34,7 @@ public interface BidirectionalGraph<N, E> extends Graph<N, E> {
      * @param node
      *         the node
      *
-     * @return all incoming edges of the specified node.
+     * @return all incoming edges of the specified node
      */
     Collection<E> getIncomingEdges(N node);
 
@@ -58,11 +58,21 @@ interface IntAbstraction<E> extends Graph.IntAbstraction<E> {
 
         /**
          * Int-abstracted version of {@link #getIncomingEdges(Object)}.
+         *
+         * @param node
+         *         the (int-abstracted) node identifier
+         *
+         * @return all incoming edges of the specified node
          */
         Collection<E> getIncomingEdges(int node);
 
         /**
          * Int-abstracted version of {@link #getSource(Object)}.
+         *
+         * @param edge
+         *         the edge
+         *
+         * @return the (int-abstracted) id of the source node of the given edge
          */
         int getIntSource(E edge);
 

api/src/main/java/net/automatalib/graph/Graph.java

@@ -79,30 +79,59 @@ interface IntAbstraction<E> extends SimpleGraph.IntAbstraction {
 
         /**
          * Int-abstracted version of {@link #getOutgoingEdges(Object)}.
+         *
+         * @param node
+         *         the (int-abstracted) node identifier
+         *
+         * @return a collection containing the outgoing edges
          */
         Collection<E> getOutgoingEdges(int node);
 
         /**
          * Int-abstracted version of {@link #getTarget(Object)}.
+         *
+         * @param edge
+         *         the edge
+         *
+         * @return the target node of the given edge.
          */
         int getIntTarget(E edge);
 
         /**
          * Int-abstracted version of {@link #getOutgoingEdgesIterator(Object)}.
+         *
+         * @param node
+         *         the (int-abstracted) node identifier
+         *
+         * @return an iterator over the outgoing edges
          */
         default Iterator<E> getOutgoingEdgesIterator(int node) {
             return getOutgoingEdges(node).iterator();
         }
 
         /**
          * (Finite) int-abstracted version of {@link #getEdgesBetween(Object, Object)}.
+         *
+         * @param from
+         *         the (int-abstracted) source node identifier
+         * @param to
+         *         the (int-abstracted) target node identifier
+         *
+         * @return an iterator over the edges between the two nodes
          */
         default Collection<E> getEdgesBetween(int from, int to) {
             return IteratorUtil.list(IteratorUtil.filter(getOutgoingEdgesIterator(from), e -> getIntTarget(e) == to));
         }
 
         /**
          * Int-abstracted version of {@link #isConnected(Object, Object)}.
+         *
+         * @param source
+         *         the (int-abstracted) source node identifier
+         * @param target
+         *         the (int-abstracted) target node identifier
+         *
+         * @return {@code true} if the nodes are connect, {@code false} otherwise
          */
         @Override
         default boolean isConnected(int source, int target) {

api/src/main/java/net/automatalib/graph/MutableGraph.java

@@ -33,8 +33,7 @@
 public interface MutableGraph<N, E, NP, EP> extends UniversalGraph<N, E, NP, EP> {
 
     /**
-     * Adds a new node with default properties to the graph. This method behaves equivalently to the below {@link
-     * #addNode(Object)} with a <code>null</code> parameter.
+     * Adds a new node (with an empty property) to the graph.
      *
      * @return the newly inserted node
      */
@@ -43,10 +42,10 @@ default N addNode() {
     }
 
     /**
-     * Adds a new node to the graph.
+     * Adds a new node with the given property to the graph.
      *
      * @param property
-     *         the property for the new node
+     *         the property of the new node
      *
      * @return the newly inserted node
      */
@@ -115,35 +114,68 @@ interface IntAbstraction<E, NP, EP> extends UniversalGraph.IntAbstraction<E, NP,
 
         /**
          * Int-abstracted version of {@link #addNode()}.
+         *
+         * @return the (int-abstracted) id of the newly inserted node
          */
         default int addIntNode() {
             return addIntNode(null);
         }
 
         /**
          * Int-abstracted version of {@link #addNode(Object)}.
+         *
+         * @param property
+         *         the property of the new node
+         *
+         * @return the (int-abstracted) id of the newly inserted node
          */
         int addIntNode(@Nullable NP property);
 
         /**
          * Int-abstracted version of {@link #connect(Object, Object)}.
+         *
+         * @param source
+         *         the (int-abstracted) id of the source node
+         * @param target
+         *         the (int-abstracted) id of the target node
+         *
+         * @return the newly created edge
          */
         default E connect(int source, int target) {
             return connect(source, target, null);
         }
 
         /**
          * Int-abstracted version of {@link #connect(Object, Object, Object)}.
+         *
+         * @param source
+         *         the (int-abstracted) id of the source node
+         * @param target
+         *         the (int-abstracted) id of the target node
+         * @param property
+         *         the property of the edge
+         *
+         * @return the newly created edge
          */
         E connect(int source, int target, @Nullable EP property);
 
         /**
          * Int-abstracted version of {@link #setNodeProperty(Object, Object)}.
+         *
+         * @param node
+         *         the (int-abstracted) id of the node
+         * @param property
+         *         the property of the node
          */
         void setNodeProperty(int node, @Nullable NP property);
 
         /**
          * Int-abstracted version of {@link MutableGraph#setEdgeProperty(Object, Object)}.
+         *
+         * @param edge
+         *         the edge
+         * @param property
+         *         the property of the edge
          */
         void setEdgeProperty(E edge, EP property);
     }

api/src/main/java/net/automatalib/graph/UniversalGraph.java

@@ -31,11 +31,21 @@ interface IntAbstraction<E, NP, EP> extends Graph.IntAbstraction<E> {
 
         /**
          * Int-abstracted version of {@link #getNodeProperty(Object)}.
+         *
+         * @param node
+         *         the (int-abstracted) node identifier
+         *
+         * @return the property of the specified node
          */
         NP getNodeProperty(int node);
 
         /**
          * Int-abstracted version of {@link UniversalIndefiniteGraph#getEdgeProperty(Object)}.
+         *
+         * @param edge
+         *         the edge
+         *
+         * @return the property of the specified edge
          */
         EP getEdgeProperty(E edge);
     }

api/src/main/java/net/automatalib/modelchecking/Lasso.java

@@ -61,12 +61,14 @@ public interface Lasso<I, D> extends DetOutputAutomaton<Integer, I, Integer, D>,
     /**
      * Gets the finite representation of the output of the lasso.
      *
-     * @return the output type D.
+     * @return the output
      */
     D getOutput();
 
     /**
      * The sorted set containing some symbol indices after which the beginning state of the loop is visited.
+     *
+     * @return the symbol indices after which the beginning state of the loop is visited
      */
     SortedSet<Integer> getLoopBeginIndices();
 

api/src/main/java/net/automatalib/visualization/VisualizationHelper.java

@@ -58,8 +58,12 @@ default void getGlobalEdgeProperties(Map<String, String> properties) {}
      * overridden, it is probably a good idea to call {@code super.getEdgeProperties(node, properties);} at the
      * beginning of the method.
      *
+     * @param src
+     *         the source node of the edge
      * @param edge
      *         the edge to be rendered
+     * @param tgt
+     *         the target node of the edge
      * @param properties
      *         the property map
      *

api/src/main/java/net/automatalib/word/Word.java

@@ -92,6 +92,8 @@ public static <I> Comparator<Word<I>> canonicalComparator(Comparator<? super I>
      *
      * @param symbols
      *         the symbol array
+     * @param <I>
+     *         symbol type
      *
      * @return a word containing the symbols in the specified array
      */
@@ -109,6 +111,9 @@ public static <I> Word<I> fromSymbols(I... symbols) {
     /**
      * Retrieves the empty word.
      *
+     * @param <I>
+     *         symbol type
+     *
      * @return the empty word.
      *
      * @see Collections#emptyList()
@@ -123,6 +128,8 @@ public static <I> Word<I> epsilon() {
      *
      * @param letter
      *         the letter
+     * @param <I>
+     *         symbol type
      *
      * @return a word consisting of only this letter
      */
@@ -140,6 +147,8 @@ public static <I> Word<I> fromLetter(I letter) {
      *         the starting index in the array
      * @param length
      *         the length of the resulting word (from the starting index on)
+     * @param <I>
+     *         symbol type
      *
      * @return the word consisting of the symbols in the range
      */
@@ -160,6 +169,8 @@ public static <I> Word<I> fromArray(I[] symbols, int offset, int length) {
      *
      * @param symbolList
      *         the list of symbols
+     * @param <I>
+     *         symbol type
      *
      * @return the resulting word
      */
@@ -226,6 +237,8 @@ public static <I> Word<I> fromWords(Collection<? extends Word<? extends I>> word
      *
      * @param word
      *         the word to upcast
+     * @param <I>
+     *         symbol type
      *
      * @return the upcasted word (reference identical to {@code word})
      */
@@ -415,7 +428,11 @@ public List<I> asList() {
     }
 
     /**
-     * Retrieves a {@link IntSeq} view on the contents of this word for a given indexing function (e.g. an {@link Alphabet}).
+     * Retrieves a {@link IntSeq} view on the contents of this word for a given indexing function (e.g. an
+     * {@link Alphabet}).
+     *
+     * @param indexFunction
+     *         the mapping from symbols to indices
      *
      * @return an {@link IntSeq} view of the contained symbols.
      */
@@ -774,6 +791,8 @@ public int[] toIntArray(ToIntFunction<? super I> toInt) {
      *
      * @param transformer
      *         the transformation function
+     * @param <T>
+     *         the target type
      *
      * @return the transformed word
      */

commons/smartcollections/src/main/java/net/automatalib/common/smartcollection/AWUtil.java

@@ -36,6 +36,10 @@ private AWUtil() {
      *         the container.
      * @param array
      *         the array
+     * @param <T>
+     *         the array type
+     * @param <U>
+     *         the container type
      *
      * @return the number of elements copied
      */
@@ -61,6 +65,10 @@ public static <T, U extends T> int safeWrite(ArrayWritable<U> aw, T[] array) {
      *         the container.
      * @param array
      *         the array
+     * @param <T>
+     *         the array type
+     * @param <U>
+     *         the container type
      *
      * @return the number of elements copied
      */

commons/smartcollections/src/main/java/net/automatalib/common/smartcollection/ArrayWritable.java

@@ -51,7 +51,9 @@ public interface ArrayWritable<T> {
     void writeToArray(int offset, @Nullable Object[] array, int tgtOfs, int num);
 
     /**
-     * The size of this container.
+     * Returns the size of this container.
+     *
+     * @return the size of this container
      */
     int size();
 }