Browse Source

Improve Javadoc of the graph package.

Mikaël Capelle 2 years ago
parent
commit
dc715744d0

+ 102
- 14
src/main/org/insa/graph/AccessRestrictions.java View File

@@ -4,47 +4,90 @@ import java.util.EnumMap;
4 4
 import java.util.EnumSet;
5 5
 
6 6
 /**
7
+ * <p>
7 8
  * Class containing access restrictions for roads/arcs.
9
+ * </p>
8 10
  * 
11
+ * <p>
9 12
  * This class maps transport modes to their restriction and provide interface
10 13
  * based on EnumSet to query restrictions.
14
+ * </p>
11 15
  * 
16
+ * <p>
12 17
  * To each transport is associated at most one restriction per road (no
13 18
  * restriction corresponds to {@link AccessRestriction#UNKNOWN} but a road can
14 19
  * have different restrictions for different modes.
20
+ * </p>
15 21
  *
16 22
  */
17 23
 public class AccessRestrictions {
18 24
 
19 25
     /**
20
-     * List of managed transport modes.
26
+     * Enumeration representing the available transport modes.
21 27
      *
28
+     * @see <a href=
29
+     *      "https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions">OpenStreetMap
30
+     *      reference for access modes.</a>
22 31
      */
23 32
     public enum AccessMode {
24 33
 
25
-        // Specific modes
34
+        /**
35
+         * Access mode corresponding to pedestrians.
36
+         */
26 37
         FOOT,
38
+
39
+        /**
40
+         * Access mode corresponding to bicycles (non-motorized).
41
+         */
27 42
         BICYCLE,
43
+
44
+        /**
45
+         * Access mode corresponding to small motorcycles (limited speed).
46
+         */
28 47
         SMALL_MOTORCYCLE,
48
+
49
+        /**
50
+         * Access mode corresponding to agricultural vehicles.
51
+         */
29 52
         AGRICULTURAL,
53
+
54
+        /**
55
+         * Access mode corresponding to motorcycles.
56
+         */
30 57
         MOTORCYCLE,
58
+
59
+        /**
60
+         * Access mode corresponding to motorcars.
61
+         */
31 62
         MOTORCAR,
63
+
64
+        /**
65
+         * Access mode corresponding to heavy transportation vehicles.
66
+         */
32 67
         HEAVY_GOODS,
68
+
69
+        /**
70
+         * Access mode corresponding to public transport vehicles.
71
+         */
33 72
         PUBLIC_TRANSPORT;
34 73
 
35 74
         /**
36
-         * EnumSet containing all the possible transport modes.
75
+         * {@code EnumSet} containing all possible transport modes.
76
+         * 
77
+         * 
37 78
          */
38 79
         public static final EnumSet<AccessMode> ALL = EnumSet.allOf(AccessMode.class);
39 80
 
40 81
         /**
41
-         * EnumSet containing all the vehicle transport modes.
82
+         * {@code EnumSet} containing all vehicle transport modes.
83
+         * 
42 84
          */
43 85
         public static final EnumSet<AccessMode> VEHICLE = EnumSet.range(AccessMode.BICYCLE,
44 86
                 AccessMode.PUBLIC_TRANSPORT);
45 87
 
46 88
         /**
47
-         * EnumSet containing all the motorized vehicle transport modes.
89
+         * {@code EnumSet} containing all motorized vehicle transport modes.
90
+         * 
48 91
          */
49 92
         public static final EnumSet<AccessMode> MOTOR_VEHICLE = EnumSet
50 93
                 .range(AccessMode.SMALL_MOTORCYCLE, AccessMode.PUBLIC_TRANSPORT);
@@ -53,11 +96,56 @@ public class AccessRestrictions {
53 96
     /**
54 97
      * Possible restrictions for the roads/arcs.
55 98
      *
99
+     * @see <a href=
100
+     *      "https://wiki.openstreetmap.org/wiki/Key:access#Transport_mode_restrictions">OpenStreetMap
101
+     *      reference for access restrictions.</a>
56 102
      */
57 103
     public enum AccessRestriction {
58
-        ALLOWED, FORBIDDEN, PRIVATE, DESTINATION, DELIVERY, CUSTOMERS, FORESTRY, UNKNOWN;
59 104
 
60
-        // Not private or forbidden
105
+        /**
106
+         * 
107
+         */
108
+        ALLOWED,
109
+
110
+        /**
111
+         * 
112
+         */
113
+        FORBIDDEN,
114
+
115
+        /**
116
+         * 
117
+         */
118
+        PRIVATE,
119
+
120
+        /**
121
+         * 
122
+         */
123
+        DESTINATION,
124
+
125
+        /**
126
+         * 
127
+         */
128
+        DELIVERY,
129
+
130
+        /**
131
+         * 
132
+         */
133
+        CUSTOMERS,
134
+
135
+        /**
136
+         * 
137
+         */
138
+        FORESTRY,
139
+
140
+        /**
141
+         * 
142
+         */
143
+        UNKNOWN;
144
+
145
+        /**
146
+         * {@code EnumSet} corresponding to restrictions that are not totally private.
147
+         * 
148
+         */
61 149
         public static final EnumSet<AccessRestriction> ALLOWED_FOR_SOMETHING = EnumSet.of(
62 150
                 AccessRestriction.ALLOWED, AccessRestriction.DESTINATION,
63 151
                 AccessRestriction.DESTINATION, AccessRestriction.DELIVERY,
@@ -82,7 +170,7 @@ public class AccessRestrictions {
82 170
      * Create a new AccessRestrictions instances with the given restrictions.
83 171
      * 
84 172
      * @param restrictions Map of restrictions for this instance of
85
-     * AccessRestrictions.
173
+     *        AccessRestrictions.
86 174
      */
87 175
     public AccessRestrictions(EnumMap<AccessMode, AccessRestriction> restrictions) {
88 176
         this.restrictions = restrictions;
@@ -106,8 +194,8 @@ public class AccessRestrictions {
106 194
      * @param mode Mode for which to check the restrictions.
107 195
      * @param restrictions List of queried restrictions for the mode.
108 196
      * 
109
-     * @return true if the restriction of the given mode is one of the given
110
-     * restrictions.
197
+     * @return {@code true} if the restriction of the given mode is one of the given
198
+     *         restrictions.
111 199
      */
112 200
     public boolean isAllowedForAny(AccessMode mode, EnumSet<AccessRestriction> restrictions) {
113 201
         return restrictions.contains(getRestrictionFor(mode));
@@ -120,8 +208,8 @@ public class AccessRestrictions {
120 208
      * @param mode Mode for which the restriction should be checked.
121 209
      * @param restriction Restriction to check against.
122 210
      * 
123
-     * @return true if the restriction of the given mode corresponds to the given
124
-     * restriction.
211
+     * @return {@code true} if the restriction of the given mode corresponds to the
212
+     *         given restriction.
125 213
      */
126 214
     public boolean isAllowedFor(AccessMode mode, AccessRestriction restriction) {
127 215
         return getRestrictionFor(mode).equals(restriction);
@@ -134,8 +222,8 @@ public class AccessRestrictions {
134 222
      * @param modes Modes for which restrictions should be checked.
135 223
      * @param restrictions Set of wanted restrictions for the modes.
136 224
      * 
137
-     * @return true if all the given modes are allowed for any of the given
138
-     * restrictions.
225
+     * @return {@code true} if all the given modes are allowed for any of the given
226
+     *         restrictions.
139 227
      */
140 228
     public boolean areAllAllowedForAny(EnumSet<AccessMode> modes,
141 229
             EnumSet<AccessRestriction> restrictions) {

+ 7
- 6
src/main/org/insa/graph/Arc.java View File

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

+ 1
- 1
src/main/org/insa/graph/ArcBackward.java View File

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

+ 6
- 2
src/main/org/insa/graph/Graph.java View File

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

+ 9
- 3
src/main/org/insa/graph/GraphStatistics.java View File

@@ -1,11 +1,16 @@
1 1
 package org.insa.graph;
2 2
 
3 3
 /**
4
+ * <p>
4 5
  * Utility class that stores some statistics of graphs that are not easy to
5 6
  * access.
7
+ * </p>
6 8
  * 
7
- * This class is used to provide O(1) access to information in graph that do not
8
- * change, and that usually require O(n) to compute.
9
+ * <p>
10
+ * This class is used to provide constant ({@code O(1)}) access to information
11
+ * in graph that do not change, and that usually require linear complexity to
12
+ * compute.
13
+ * </p>
9 14
  *
10 15
  */
11 16
 public class GraphStatistics {
@@ -13,6 +18,7 @@ public class GraphStatistics {
13 18
     /**
14 19
      * Special value used to indicate that the graph has no maximum speed limit
15 20
      * (some roads are not limited).
21
+     * 
16 22
      */
17 23
     public static final int NO_MAXIMUM_SPEED = -1;
18 24
 
@@ -38,7 +44,7 @@ public class GraphStatistics {
38 44
         }
39 45
 
40 46
         /**
41
-         * @return Bottom-right point of this boundin box.
47
+         * @return Bottom-right point of this bounding box.
42 48
          */
43 49
         public Point getBottomRightPoint() {
44 50
             return bottomRight;

+ 13
- 3
src/main/org/insa/graph/Node.java View File

@@ -5,23 +5,33 @@ import java.util.Collections;
5 5
 import java.util.List;
6 6
 
7 7
 /**
8
+ * <p>
8 9
  * Class representing a Node in a {@link Graph}.
10
+ * </p>
9 11
  * 
12
+ * <p>
10 13
  * This class holds information regarding nodes in the graph together with the
11 14
  * successors associated to the nodes.
15
+ * </p>
12 16
  * 
17
+ * <p>
13 18
  * Nodes are comparable based on their ID.
19
+ * </p>
14 20
  *
15 21
  */
16 22
 public final class Node implements Comparable<Node> {
17 23
 
18 24
     /**
25
+     * <p>
19 26
      * Link the two given nodes with one or two arcs (depending on roadInformation),
20 27
      * with the given attributes.
28
+     * </p>
21 29
      * 
22
-     * If `roadInformation.isOneWay()` is true, only a forward arc is created
23
-     * (origin to destination) and added to origin. Otherwise, a corresponding
24
-     * backward arc is created and add to destination.
30
+     * <p>
31
+     * If {@code roadInformation.isOneWay()} is {@code true}, only a forward arc is
32
+     * created (origin to destination) and added to origin. Otherwise, a
33
+     * corresponding backward arc is created and add to destination.
34
+     * </p>
25 35
      * 
26 36
      * @param origin Origin of the arc.
27 37
      * @param destination Destination of the arc.

+ 7
- 2
src/main/org/insa/graph/Path.java View File

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

+ 12
- 4
src/main/org/insa/graph/RoadInformation.java View File

@@ -1,16 +1,24 @@
1 1
 package org.insa.graph;
2 2
 
3 3
 /**
4
+ * <p>
4 5
  * Class containing information for road that may be shared by multiple arcs.
6
+ * </p>
5 7
  * 
6
- * Sharing information between arcs reduces memory footprints of the program - A
7
- * long road is often split into multiple arcs at each intersection.
8
+ * <p>
9
+ * Sharing information between arcs reduces memory footprints of the program (a
10
+ * long road is often split into multiple arcs at each intersection).
11
+ * </p>
8 12
  * 
9 13
  */
10 14
 public class RoadInformation {
11 15
 
12 16
     /**
13
-     * Road type.
17
+     * Enumeration for road types.
18
+     * 
19
+     * @see <a href=
20
+     *      "https://wiki.openstreetmap.org/wiki/Key:highway#Values">OpenStreetMap
21
+     *      reference for road types.</a>
14 22
      */
15 23
     public enum RoadType {
16 24
         MOTORWAY,
@@ -53,7 +61,7 @@ public class RoadInformation {
53 61
      * 
54 62
      * @param roadType Type of the road (see {@link RoadType}).
55 63
      * @param access Access restrictions for the road (see
56
-     * {@link AccessRestrictions}).
64
+     *        {@link AccessRestrictions}).
57 65
      * @param isOneWay true if this road is a one way road, false otherwise.
58 66
      * @param maxSpeed Maximum speed for the road (in kilometers-per-hour).
59 67
      * @param name Name of the road.

Loading…
Cancel
Save