Update javadoc.

src/main/org/insa/algo/AbstractAlgorithm.java

@@ -4,13 +4,23 @@ import java.time.Duration;
 import java.time.Instant;
 import java.util.ArrayList;
 
+/**
+ * Base class for algorithm classes.
+ *
+ * @param <Observer> Observer type for the algorithm.
+ */
 public abstract class AbstractAlgorithm<Observer> {
 
-    protected AbstractInputData data;
-    protected ArrayList<Observer> observers;
+    // Input data for the algorithm
+    protected final AbstractInputData data;
+
+    // List of observers for the algorithm
+    protected final ArrayList<Observer> observers;
 
     /**
-     * @param data
+     * Create a new algorithm with an empty list of observers.
+     * 
+     * @param data Input data for the algorithm.
      */
     protected AbstractAlgorithm(AbstractInputData data) {
         this.data = data;
@@ -18,19 +28,20 @@ public abstract class AbstractAlgorithm<Observer> {
     }
 
     /**
-     * @param data
-     * @param observers
+     * Create a new algorithm with the given list of observers.
+     * 
+     * @param data Input data for the algorithm.
+     * @param observers Initial list of observers for the algorithm.
      */
     protected AbstractAlgorithm(AbstractInputData data, ArrayList<Observer> observers) {
         this.data = data;
         this.observers = observers;
-        ;
     }
 
     /**
      * Add an observer to this algorithm.
      * 
-     * @param observer
+     * @param observer Observer to add to this algorithm.
      */
     public void addObserver(Observer observer) {
         observers.add(observer);
@@ -44,16 +55,19 @@ public abstract class AbstractAlgorithm<Observer> {
     }
 
     /**
-     * @return Instance corresponding to this algorithm.
+     * @return Input for this algorithm.
      */
     public AbstractInputData getInputData() {
         return data;
     }
 
     /**
-     * Run the algorithm and update the current solution.
+     * Run the algorithm and return the solution.
      * 
-     * @return true if a feasible solution was found (even non-optimal).
+     * This methods internally time the call to doRun() and update the result of the
+     * call with the computed solving time.
+     * 
+     * @return The solution found by the algorithm (may not be a feasible solution).
      */
     public AbstractSolution run() {
         Instant start = Instant.now();
@@ -65,7 +79,8 @@ public abstract class AbstractAlgorithm<Observer> {
     /**
      * Abstract method that should be implemented by child class.
      * 
-     * @return A solution, if one was found, or null.
+     * @return The solution found, must not be null (use an infeasible or unknown
+     * status if necessary).
      */
     protected abstract AbstractSolution doRun();
 

src/main/org/insa/algo/AbstractInputData.java

@@ -3,20 +3,33 @@ package org.insa.algo;
 import org.insa.graph.Arc;
 import org.insa.graph.Graph;
 
+/**
+ * Base class for algorithm input data classes. This class contains the basic
+ * data that are required by most graph algorithms, i.e. a graph, a mode (time /
+ * length) and a filter for the arc.
+ *
+ */
 public abstract class AbstractInputData {
 
+    /**
+     * Mode for computing costs on the arc (time or length).
+     *
+     */
     public enum Mode {
         TIME, LENGTH
     }
 
     /**
-     * 
+     * Filtering inteface for arcs - This class can be used to indicate to an
+     * algorithm which arc can be used.
      *
      */
     public interface ArcFilter {
 
         /**
-         * @param arc
+         * Check if the given arc can be used (is allowed).
+         * 
+         * @param arc Arc to check.
          * 
          * @return true if the given arc is allowed.
          */
@@ -25,18 +38,20 @@ public abstract class AbstractInputData {
     }
 
     // Graph
-    protected Graph graph;
+    private final Graph graph;
 
     // Mode for the computation of the costs.
-    private final AbstractInputData.Mode mode;
+    private final Mode mode;
 
     // Arc filter.
-    private final AbstractInputData.ArcFilter arcFilter;
+    private final ArcFilter arcFilter;
 
     /**
      * Create a new AbstractInputData instance for the given graph, mode and filter.
      * 
      * @param graph
+     * @parma mode
+     * @param arcFilter
      */
     protected AbstractInputData(Graph graph, Mode mode, ArcFilter arcFilter) {
         this.graph = graph;
@@ -65,15 +80,9 @@ public abstract class AbstractInputData {
      * mode (LENGHT), with no filtering on the arc.
      * 
      * @param graph
-     * @param mode
      */
     protected AbstractInputData(Graph graph) {
-        this(graph, Mode.LENGTH, new AbstractInputData.ArcFilter() {
-            @Override
-            public boolean isAllowed(Arc arc) {
-                return true;
-            }
-        });
+        this(graph, Mode.LENGTH);
     }
 
     /**
@@ -85,13 +94,21 @@ public abstract class AbstractInputData {
 
     /**
      * @return Mode of the algorithm (time or length).
+     * 
+     * @see Mode
      */
     public Mode getMode() {
         return mode;
     }
 
     /**
+     * Check if the given arc is allowed for the filter corresponding to this input.
+     * 
+     * @param arc Arc to check.
+     * 
      * @return true if the given arc is allowed.
+     * 
+     * @see ArcFilter
      */
     public boolean isAllowed(Arc arc) {
         return this.arcFilter.isAllowed(arc);

src/main/org/insa/algo/AbstractSolution.java

@@ -2,6 +2,12 @@ package org.insa.algo;
 
 import java.time.Duration;
 
+/**
+ * Base class for solution classes returned by the algorithm. This class
+ * contains the basic information that any solution should have: status of the
+ * solution (unknown, infeasible, etc.), solving time and the original input
+ * data.
+ */
 public abstract class AbstractSolution {
 
     /**
@@ -13,13 +19,13 @@ public abstract class AbstractSolution {
     };
 
     // Status of the solution.
-    Status status;
+    private final Status status;
 
     // Solving time for the solution.
-    Duration solvingTime;
+    private Duration solvingTime;
 
     // Original input of the solution.
-    AbstractInputData data;
+    private final AbstractInputData data;
 
     /**
      * Create a new abstract solution with unknown status.

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

@@ -3,8 +3,23 @@ package org.insa.graph;
 import java.util.EnumMap;
 import java.util.EnumSet;
 
+/**
+ * Class containing access restrictions for roads/arcs.
+ * 
+ * This class maps transport modes to their restriction and provide interface
+ * based on EnumSet to query restrictions.
+ * 
+ * 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.
+ *
+ */
 public class AccessRestrictions {
 
+    /**
+     * List of managed transport modes.
+     *
+     */
     public enum AccessMode {
 
         // Specific modes
@@ -17,18 +32,28 @@ public class AccessRestrictions {
         HEAVY_GOODS,
         PUBLIC_TRANSPORT;
 
-        // All available modes
+        /**
+         * EnumSet containing all the possible transport modes.
+         */
         public static final EnumSet<AccessMode> ALL = EnumSet.allOf(AccessMode.class);
 
-        // Vehicle
+        /**
+         * EnumSet containing all the vehicle transport modes.
+         */
         public static final EnumSet<AccessMode> VEHICLE = EnumSet.range(AccessMode.BICYCLE,
                 AccessMode.PUBLIC_TRANSPORT);
 
-        // Motor vehicle
+        /**
+         * EnumSet containing all the motorized vehicle transport modes.
+         */
         public static final EnumSet<AccessMode> MOTOR_VEHICLE = EnumSet
                 .range(AccessMode.SMALL_MOTORCYCLE, AccessMode.PUBLIC_TRANSPORT);
     }
 
+    /**
+     * Possible restrictions for the roads/arcs.
+     *
+     */
     public enum AccessRestriction {
         ALLOWED, FORBIDDEN, PRIVATE, DESTINATION, DELIVERY, CUSTOMERS, FORESTRY, UNKNOWN;
 
@@ -44,7 +69,7 @@ public class AccessRestrictions {
     private final EnumMap<AccessMode, AccessRestriction> restrictions;
 
     /**
-     * Create new access restrictions with unknown restrictions.
+     * Create new AccessRestrictions instances with unknown restrictions.
      */
     public AccessRestrictions() {
         this.restrictions = new EnumMap<>(AccessMode.class);
@@ -54,16 +79,19 @@ public class AccessRestrictions {
     }
 
     /**
-     * Create a new instance of access restrictions with the given restrictions.
+     * Create a new AccessRestrictions instances with the given restrictions.
      * 
-     * @param restrictions
+     * @param restrictions Map of restrictions for this instance of
+     * AccessRestrictions.
      */
     public AccessRestrictions(EnumMap<AccessMode, AccessRestriction> restrictions) {
         this.restrictions = restrictions;
     }
 
     /**
-     * @param mode
+     * Retrieve the restriction corresponding to the given mode.
+     * 
+     * @param mode Mode for which the restriction should be retrieved.
      * 
      * @return Restriction for the given mode.
      */
@@ -72,28 +100,39 @@ public class AccessRestrictions {
     }
 
     /**
-     * @param mode
-     * @param restrictions
+     * Check if the restriction associated with the given mode is one of the given
+     * restrictions.
      * 
-     * @return true if the given mode is allowed for any of the given restrictions.
+     * @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
+     * restrictions.
      */
     public boolean isAllowedForAny(AccessMode mode, EnumSet<AccessRestriction> restrictions) {
         return restrictions.contains(getRestrictionFor(mode));
     }
 
     /**
-     * @param mode
-     * @param restriction
+     * Check if the restriction for the given mode corresponds to the given
+     * restriction.
      * 
-     * @return true if the given mode is allowed for the given restriction.
+     * @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.
      */
     public boolean isAllowedFor(AccessMode mode, AccessRestriction restriction) {
         return getRestrictionFor(mode).equals(restriction);
     }
 
     /**
-     * @param modes
-     * @param restrictions
+     * Check if the restriction associated to each given mode is one of the
+     * restrictions. The restriction may not be the same for all modes.
+     * 
+     * @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
      * restrictions.