* 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. + * Enumeration representing the available transport modes. * + * @see OpenStreetMap + * reference for access modes. */ 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+ * 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). + *
* + ** 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 + *
* */ public abstract class Arc { diff --git a/src/main/org/insa/graph/ArcBackward.java b/src/main/org/insa/graph/ArcBackward.java index 4ea6cae..7ce9fca 100644 --- a/src/main/org/insa/graph/ArcBackward.java +++ b/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. * diff --git a/src/main/org/insa/graph/Graph.java b/src/main/org/insa/graph/Graph.java index 867b715..b188c91 100644 --- a/src/main/org/insa/graph/Graph.java +++ b/src/main/org/insa/graph/Graph.java @@ -5,10 +5,14 @@ import java.util.Collections; import java.util.List; /** + ** Main graph class. + *
* - * 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. + *+ * 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. + *
* */ public final class Graph { diff --git a/src/main/org/insa/graph/GraphStatistics.java b/src/main/org/insa/graph/GraphStatistics.java index 0688e1b..f5c1e98 100644 --- a/src/main/org/insa/graph/GraphStatistics.java +++ b/src/main/org/insa/graph/GraphStatistics.java @@ -1,11 +1,16 @@ package org.insa.graph; /** + ** Utility class that stores some statistics of graphs that are not easy to * access. + *
* - * 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. + *+ * 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. + *
* */ 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; diff --git a/src/main/org/insa/graph/Node.java b/src/main/org/insa/graph/Node.java index 964c8fb..cb785e7 100644 --- a/src/main/org/insa/graph/Node.java +++ b/src/main/org/insa/graph/Node.java @@ -5,23 +5,33 @@ import java.util.Collections; import java.util.List; /** + ** Class representing a Node in a {@link Graph}. + *
* + ** This class holds information regarding nodes in the graph together with the * successors associated to the nodes. + *
* + ** Nodes are comparable based on their ID. + *
* */ public final class Node implements Comparable* Link the two given nodes with one or two arcs (depending on roadInformation), * with the given attributes. + *
* - * 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. + *+ * 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. + *
* * @param origin Origin of the arc. * @param destination Destination of the arc. diff --git a/src/main/org/insa/graph/Path.java b/src/main/org/insa/graph/Path.java index d2c81a1..72c5845 100644 --- a/src/main/org/insa/graph/Path.java +++ b/src/main/org/insa/graph/Path.java @@ -5,10 +5,15 @@ import java.util.Collections; import java.util.List; /** + ** Class representing a path between nodes in a graph. + *
* - * 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. + *+ * 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. + *
* */ public class Path { diff --git a/src/main/org/insa/graph/RoadInformation.java b/src/main/org/insa/graph/RoadInformation.java index fd6c3b4..61aed04 100644 --- a/src/main/org/insa/graph/RoadInformation.java +++ b/src/main/org/insa/graph/RoadInformation.java @@ -1,16 +1,24 @@ package org.insa.graph; /** + ** Class containing information for road that may be shared by multiple arcs. + *
* - * Sharing information between arcs reduces memory footprints of the program - A - * long road is often split into multiple arcs at each intersection. + *+ * Sharing information between arcs reduces memory footprints of the program (a + * long road is often split into multiple arcs at each intersection). + *
* */ public class RoadInformation { /** - * Road type. + * Enumeration for road types. + * + * @see OpenStreetMap + * reference for road types. */ public enum RoadType { MOTORWAY, @@ -53,7 +61,7 @@ public class RoadInformation { * * @param roadType Type of the road (see {@link RoadType}). * @param access Access restrictions for the road (see - * {@link AccessRestrictions}). + * {@link AccessRestrictions}). * @param isOneWay true if this road is a one way road, false otherwise. * @param maxSpeed Maximum speed for the road (in kilometers-per-hour). * @param name Name of the road.