Improve Javadoc of the graph package.

src/main/org/insa/graph/AccessRestrictions.java

@@ -4,47 +4,90 @@ import java.util.EnumMap;
 import java.util.EnumSet;
 
 /**
+ * <p>
  * Class containing access restrictions for roads/arcs.
+ * </p>
  * 
+ * <p>
  * This class maps transport modes to their restriction and provide interface
  * based on EnumSet to query restrictions.
+ * </p>
  * 
+ * <p>
  * To each transport is associated at most one restriction per road (no
  * restriction corresponds to {@link AccessRestriction#UNKNOWN} but a road can
  * have different restrictions for different modes.
+ * </p>
  *
  */
 public class AccessRestrictions {
 
     /**
-     * List of managed transport modes.
+     * Enumeration representing the available transport modes.
      *
+     * @see <a href=
+     *      "https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions">OpenStreetMap
+     *      reference for access modes.</a>
      */
     public enum AccessMode {
 
-        // Specific modes
+        /**
+         * Access mode corresponding to pedestrians.
+         */
         FOOT,
+
+        /**
+         * Access mode corresponding to bicycles (non-motorized).
+         */
         BICYCLE,
+
+        /**
+         * Access mode corresponding to small motorcycles (limited speed).
+         */
         SMALL_MOTORCYCLE,
+
+        /**
+         * Access mode corresponding to agricultural vehicles.
+         */
         AGRICULTURAL,
+
+        /**
+         * Access mode corresponding to motorcycles.
+         */
         MOTORCYCLE,
+
+        /**
+         * Access mode corresponding to motorcars.
+         */
         MOTORCAR,
+
+        /**
+         * Access mode corresponding to heavy transportation vehicles.
+         */
         HEAVY_GOODS,
+
+        /**
+         * Access mode corresponding to public transport vehicles.
+         */
         PUBLIC_TRANSPORT;
 
         /**
-         * EnumSet containing all the possible transport modes.
+         * {@code EnumSet} containing all possible transport modes.
+         * 
+         * 
          */
         public static final EnumSet<AccessMode> ALL = EnumSet.allOf(AccessMode.class);
 
         /**
-         * EnumSet containing all the vehicle transport modes.
+         * {@code EnumSet} containing all vehicle transport modes.
+         * 
          */
         public static final EnumSet<AccessMode> VEHICLE = EnumSet.range(AccessMode.BICYCLE,
                 AccessMode.PUBLIC_TRANSPORT);
 
         /**
-         * EnumSet containing all the motorized vehicle transport modes.
+         * {@code EnumSet} containing all motorized vehicle transport modes.
+         * 
          */
         public static final EnumSet<AccessMode> MOTOR_VEHICLE = EnumSet
                 .range(AccessMode.SMALL_MOTORCYCLE, AccessMode.PUBLIC_TRANSPORT);
@@ -53,11 +96,56 @@ public class AccessRestrictions {
     /**
      * Possible restrictions for the roads/arcs.
      *
+     * @see <a href=
+     *      "https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions">OpenStreetMap
+     *      reference for access restrictions.</a>
      */
     public enum AccessRestriction {
-        ALLOWED, FORBIDDEN, PRIVATE, DESTINATION, DELIVERY, CUSTOMERS, FORESTRY, UNKNOWN;
 
-        // Not private or forbidden
+        /**
+         * 
+         */
+        ALLOWED,
+
+        /**
+         * 
+         */
+        FORBIDDEN,
+
+        /**
+         * 
+         */
+        PRIVATE,
+
+        /**
+         * 
+         */
+        DESTINATION,
+
+        /**
+         * 
+         */
+        DELIVERY,
+
+        /**
+         * 
+         */
+        CUSTOMERS,
+
+        /**
+         * 
+         */
+        FORESTRY,
+
+        /**
+         * 
+         */
+        UNKNOWN;
+
+        /**
+         * {@code EnumSet} corresponding to restrictions that are not totally private.
+         * 
+         */
         public static final EnumSet<AccessRestriction> ALLOWED_FOR_SOMETHING = EnumSet.of(
                 AccessRestriction.ALLOWED, AccessRestriction.DESTINATION,
                 AccessRestriction.DESTINATION, AccessRestriction.DELIVERY,
@@ -106,7 +194,7 @@ public class AccessRestrictions {
      * @param mode Mode for which to check the restrictions.
      * @param restrictions List of queried restrictions for the mode.
      * 
-     * @return true if the restriction of the given mode is one of the given
+     * @return {@code true} if the restriction of the given mode is one of the given
      *         restrictions.
      */
     public boolean isAllowedForAny(AccessMode mode, EnumSet<AccessRestriction> restrictions) {
@@ -120,8 +208,8 @@ public class AccessRestrictions {
      * @param mode Mode for which the restriction should be checked.
      * @param restriction Restriction to check against.
      * 
-     * @return true if the restriction of the given mode corresponds to the given
-     * restriction.
+     * @return {@code true} if the restriction of the given mode corresponds to the
+     *         given restriction.
      */
     public boolean isAllowedFor(AccessMode mode, AccessRestriction restriction) {
         return getRestrictionFor(mode).equals(restriction);
@@ -134,7 +222,7 @@ public class AccessRestrictions {
      * @param modes Modes for which restrictions should be checked.
      * @param restrictions Set of wanted restrictions for the modes.
      * 
-     * @return true if all the given modes are allowed for any of the given
+     * @return {@code true} if all the given modes are allowed for any of the given
      *         restrictions.
      */
     public boolean areAllAllowedForAny(EnumSet<AccessMode> modes,

src/main/org/insa/graph/Arc.java

@@ -3,17 +3,18 @@ package org.insa.graph;
 import java.util.List;
 
 /**
- * Interface representing an arc in the graph - Arc is an interface and not a
- * class to allow us to represent two-ways roads in a memory efficient manner
- * (without having to duplicate attributes).
+ * <p>
+ * Interface representing an arc in the graph. {@code Arc} is an interface and
+ * not a class to allow us to represent two-ways roads in a memory efficient
+ * manner (without having to duplicate attributes).
+ * </p>
  * 
+ * <p>
  * Arc should never be created manually but always using the
  * {@link Node#linkNodes(Node, Node, float, RoadInformation, java.util.ArrayList)}
  * method to ensure proper instantiation of the {@link ArcForward} and
  * {@link ArcBackward} classes.
- * 
- * @see ArcForward
- * @see ArcBackward
+ * </p>
  *
  */
 public abstract class Arc {

src/main/org/insa/graph/ArcBackward.java

@@ -5,7 +5,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Implementation of Arc that represents a "backward" arc in a graph, i.e. an
+ * Implementation of Arc that represents a "backward" arc in a graph, i.e., an
  * arc that is the reverse of another one. This arc only holds a reference to
  * the original arc.
  *

src/main/org/insa/graph/Graph.java

@@ -5,10 +5,14 @@ import java.util.Collections;
 import java.util.List;
 
 /**
+ * <p>
  * Main graph class.
+ * </p>
  * 
- * This class acts as a object-oriented adjacency list for a graph, i.e. it
- * holds a list of nodes and each node holds a list of its successors.
+ * <p>
+ * This class acts as a object-oriented <b>adjacency list</b> for a graph, i.e.,
+ * it holds a list of nodes and each node holds a list of its successors.
+ * </p>
  *
  */
 public final class Graph {

src/main/org/insa/graph/GraphStatistics.java

@@ -1,11 +1,16 @@
 package org.insa.graph;
 
 /**
+ * <p>
  * Utility class that stores some statistics of graphs that are not easy to
  * access.
+ * </p>
  * 
- * This class is used to provide O(1) access to information in graph that do not
- * change, and that usually require O(n) to compute.
+ * <p>
+ * This class is used to provide constant ({@code O(1)}) access to information
+ * in graph that do not change, and that usually require linear complexity to
+ * compute.
+ * </p>
  *
  */
 public class GraphStatistics {
@@ -13,6 +18,7 @@ public class GraphStatistics {
     /**
      * Special value used to indicate that the graph has no maximum speed limit
      * (some roads are not limited).
+     * 
      */
     public static final int NO_MAXIMUM_SPEED = -1;
 
@@ -38,7 +44,7 @@ public class GraphStatistics {
         }
 
         /**
-         * @return Bottom-right point of this boundin box.
+         * @return Bottom-right point of this bounding box.
          */
         public Point getBottomRightPoint() {
             return bottomRight;

src/main/org/insa/graph/Node.java

@@ -5,23 +5,33 @@ import java.util.Collections;
 import java.util.List;
 
 /**
+ * <p>
  * Class representing a Node in a {@link Graph}.
+ * </p>
  * 
+ * <p>
  * This class holds information regarding nodes in the graph together with the
  * successors associated to the nodes.
+ * </p>
  * 
+ * <p>
  * Nodes are comparable based on their ID.
+ * </p>
  *
  */
 public final class Node implements Comparable<Node> {
 
     /**
+     * <p>
      * Link the two given nodes with one or two arcs (depending on roadInformation),
      * with the given attributes.
+     * </p>
      * 
-     * If `roadInformation.isOneWay()` is true, only a forward arc is created
-     * (origin to destination) and added to origin. Otherwise, a corresponding
-     * backward arc is created and add to destination.
+     * <p>
+     * If {@code roadInformation.isOneWay()} is {@code true}, only a forward arc is
+     * created (origin to destination) and added to origin. Otherwise, a
+     * corresponding backward arc is created and add to destination.
+     * </p>
      * 
      * @param origin Origin of the arc.
      * @param destination Destination of the arc.

src/main/org/insa/graph/Path.java

@@ -5,10 +5,15 @@ import java.util.Collections;
 import java.util.List;
 
 /**
+ * <p>
  * Class representing a path between nodes in a graph.
+ * </p>
  * 
- * A path is represented as a list of {@link Arc} and not a list of {@link Node}
- * due to the multigraph nature of the considered graphs.
+ * <p>
+ * A path is represented as a list of {@link Arc} with an origin and not a list
+ * of {@link Node} due to the multi-graph nature (multiple arcs between two
+ * nodes) of the considered graphs.
+ * </p>
  *
  */
 public class Path {

src/main/org/insa/graph/RoadInformation.java

@@ -1,16 +1,24 @@
 package org.insa.graph;
 
 /**
+ * <p>
  * Class containing information for road that may be shared by multiple arcs.
+ * </p>
  * 
- * Sharing information between arcs reduces memory footprints of the program - A
- * long road is often split into multiple arcs at each intersection.
+ * <p>
+ * Sharing information between arcs reduces memory footprints of the program (a
+ * long road is often split into multiple arcs at each intersection).
+ * </p>
  * 
  */
 public class RoadInformation {
 
     /**
-     * Road type.
+     * Enumeration for road types.
+     * 
+     * @see <a href=
+     *      "https://wiki.openstreetmap.org/wiki/Key:highway#Values">OpenStreetMap
+     *      reference for road types.</a>
      */
     public enum RoadType {
         MOTORWAY,