Improve Javadoc of the graph package.

This commit is contained in:
Mikaël Capelle 2019-03-18 21:34:10 +01:00
parent 423e36fc65
commit dc715744d0
8 changed files with 157 additions and 35 deletions

View File

@ -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,

View File

@ -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 {

View File

@ -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.
*

View File

@ -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 {

View File

@ -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;

View File

@ -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.

View File

@ -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 {

View File

@ -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,