Javadoc itinerary package

src/main/java/fr/u_paris/gla/project/itinerary/Connection.java

@@ -3,6 +3,10 @@ package fr.u_paris.gla.project.itinerary;
 import java.util.ArrayList;
 import java.util.Collections;
 
+/**
+ * A representation of a connection to another stop.
+ * Corresponds to a graph edge for the algorithm.
+ */
 public class Connection{
     // Destination of the connection between the two stops
     private final Stop stop;
@@ -20,6 +24,13 @@ public class Connection{
 
     private final int bifurcation;
 
+    /**
+     * @param stop the stop where the connection is going.
+     * @param lineName the name of the line used by the connection
+     * @param distance the distance of the connection in km
+     * @param time the travel time in s
+     * @param bifurcation the bifurcation used
+     */
     public Connection(Stop stop, String lineName, double distance, int time, int bifurcation){
         this.stop = stop;
         this.lineName=lineName;
@@ -29,39 +40,78 @@ public class Connection{
         this.bifurcation = bifurcation;
     }
 
+    /**
+     * @param stop the stop where the connection is going.
+     * @param lineName the name of the line used by the connection
+     * @param distance the distance of the connection in km
+     * @param time the travel time in s
+     */
     public Connection(Stop stop, String lineName, double distance, int time){
         this(stop, lineName, distance, time, 0);
     }
 
 
+    /**
+     * Returns the line name of the connection
+     * @return the line name of the connection
+     */
     public String getLineName() {
         return lineName;
     }
 
+
+    /**
+     * Returns the distance between the two connection stops.
+     * @return distance in km
+     */
     public double getDistance() {
         return distance;
     }
 
+    /**
+     * Returns the travel time between the two stops.
+     * @return time in s
+     */
     public int getTime() {
         return time;
     }
 
+    /**
+     * Returns the stop to which the connection is going.
+     * @return the destination stop
+     */
     public Stop getStop() {
         return stop;
     }
 
+    /**
+     * Adds a schedule for the connection.
+     * @param hours passage time in s from 00:00
+     */
     public void addSchedule(int hours) {
         this.schedules.add(hours);
     }
 
+    /**
+     * Sort schedules.
+     * Necessary to get the right passage time.
+     */
     public void sortSchedule() {
         Collections.sort(this.schedules);
     }
 
+    /**
+     * Return to the schedule list
+     * @return the schedule list
+     */
     public ArrayList<Integer> getSchedules() {
         return this.schedules;
     }
 
+    /**
+     * Returns the number of bifurcation of the connection
+     * @return the bifurcation
+     */
     public int getBifurcation() {
         return this.bifurcation;
     }
@@ -70,6 +120,11 @@ public class Connection{
         return this.time;
     }
 
+    /**
+     * Returns the time of the next passage.
+     * @param currentTime the current time
+     * @return the time of the next passage
+     */
     public double getNextTime(double currentTime) {
         if(this.schedules.size() == 0) {
             return currentTime;
@@ -85,6 +140,12 @@ public class Connection{
         return this.schedules.get(0);
     }
 
+    /**
+     * Returns the time before you can reach the next stop with this connection.
+     * Corresponds to the sum of time to next stop and travel time.
+     * @param currentTime the current time
+     * @return time to reach the next stop
+     */
     public double getCost(double currentTime) {
         if(this.schedules.size() == 0) {
             if(this.lineName.equals("WALK") || this.lineName.equals("")) {

src/main/java/fr/u_paris/gla/project/itinerary/Finder.java

@@ -4,7 +4,11 @@ import fr.u_paris.gla.project.utils.GPS;
 
 import java.util.*;
 
-
+/**
+ * Path finder algorithm.
+ * The algorithm is based on an A* algorithm,
+ * adapted to our case of path finding in a public transport network.
+ */
 public class Finder  {
     private Graph graph;
 
@@ -12,6 +16,15 @@ public class Finder  {
         this.graph = graph;
     }
 
+    /**
+     *
+     * @param from_x the latitude of the starting point in decimal degrees (DD)
+     * @param from_y the longitude of the starting point
+     * @param to_x the latitude of the arrival point
+     * @param to_y the longitude of the arrival point
+     * @param startTime the departure time
+     * @return the optimal path found by the algorithm
+     */
     public List<Path> findPath(double from_x, double from_y, double to_x, double to_y, double startTime) {
         Stop fromNode = new Stop("", "tmp_from", from_x, from_y);
         Stop toNode = new Stop("", "tmp_to", to_x, to_y);

src/main/java/fr/u_paris/gla/project/itinerary/Graph.java

@@ -5,32 +5,62 @@ import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * A representation of a graph
+ * for our path-finding algorithm
+ */
 public class Graph {
     private final Set<Stop> nodes;
 
     private final Map<Stop, Set<Connection>> connections;
 
+    /**
+     * @param nodes the set of graph nodes
+     * @param connections the map of all nodes to their edges
+     */
     public Graph(Set<Stop> nodes, Map<Stop, Set<Connection>> connections) {
         this.nodes = nodes;
         this.connections = connections;
     }
 
+    /**
+     * Returns the set of edges of a node
+     * @param node the node from which we want to get the edges
+     * @return the sets of the edges for the given node
+     */
     public Set<Connection> getConnections(Stop node) {
         return connections.get(node);
     }
 
+    /**
+     * Returns the set of graph nodes
+     * @return the set of nodes
+     */
     public Set<Stop> getNodes() {
         return nodes;
     }
 
+    /**
+     * Returns the map of all nodes to their edges in the graph
+     * @return the map of all nodes to their edges
+     */
     public Map<Stop, Set<Connection>> getConnections() {
         return connections;
     }
 
+    /**
+     * Add a node to the graph
+     * @param s the node to add
+     */
     public void addNode(Stop s) {
         nodes.add(s);
     }
 
+    /**
+     * Add a connection to the graph
+     * @param stop the node from which the connection starts
+     * @param con the connection to add
+     */
     public void addConnection(Stop stop, Connection con) {
         Set<Connection> currentConnections =  connections.get(stop);
         if (currentConnections == null) {
@@ -42,7 +72,12 @@ public class Graph {
             currentConnections.add(con);
         }
     }
-    
+
+    /**
+     * Remove a node from the graph.
+     * This also removes all connections to and from this node.
+     * @param s the node to be removed
+     */
     public void removeNode(Stop s) {
         for(Stop stop : nodes) {
             if(getConnections(stop) == null) {

src/main/java/fr/u_paris/gla/project/itinerary/Parse.java

@@ -9,6 +9,9 @@ import java.util.*;
 import java.util.logging.Level;
 import java.util.logging.Logger;
 
+/**
+ * CSV file parser to generate the network graph
+ */
 public class Parse {
     private static final Logger LOGGER = Logger
             .getLogger(IDFMNetworkExtractor.class.getName());
@@ -182,6 +185,13 @@ public class Parse {
         }
     }
 
+
+    /**
+     * Adds schedules to graph stops, parsed from a CSV line
+     * @param input the current line we want to parse
+     * @param stopsHashSet the map of stop names to their objects
+     * @param connections the map of stops to their connections
+     */
     private static void addSchedule(String[] input, HashMap<String, ArrayList<Stop>> stopsHashSet, HashMap<Stop, Set<Connection>> connections) {
 
         String line = input[0];
@@ -211,6 +221,9 @@ public class Parse {
         }
     }
 
+    /**
+     * Parse CSV files to build the network graph
+     */
     public void parseFiles(){
         IDFMNetworkExtractor.buildFiles();
 
@@ -232,6 +245,10 @@ public class Parse {
         }
     }
 
+    /**
+     * Returns network graph from parsed CSV files
+     * @return the graphe of the network
+     */
     public Graph createGraph() {
         return new Graph(nodes, connections);
     }

src/main/java/fr/u_paris/gla/project/itinerary/Path.java

@@ -1,5 +1,8 @@
 package fr.u_paris.gla.project.itinerary;
 
+/**
+ * A representation of a path
+ */
 public class Path {
     private Stop current;
 
@@ -15,6 +18,11 @@ public class Path {
 
     private Connection connection;
 
+    /**
+     * @param current the start stop
+     * @param connection the connection to the next stop
+     * @param startTime departure time from node current
+     */
     public Path(Stop current, Connection connection, double startTime) {
         this.current = current;
         this.connection = connection;
@@ -24,26 +32,50 @@ public class Path {
         this.line = connection.getLineName();
     }
 
+    /**
+     * Returns the connection used by the path
+     * @return the connection used
+     */
     public Connection getConnection(){
         return this.connection;
     }
 
+    /**
+     * Returns the start stop
+     * @return the start stop
+     */
     public Stop getCurrentStop() {
         return this.current;
     }
 
+    /**
+     * Returns the next stop
+     * @return the next stop
+     */
     public Stop getNextStop() {
         return next;
     }
 
+    /**
+     * Returns stop start time
+     * @return the time in s
+     */
     public double getStartTime() {
         return this.startTime;
     }
 
+    /**
+     * Returns the travel time between the two stops.
+     * @return the travel time in s
+     */
     public double travelTime() {
         return this.travelTime;
     }
 
+    /**
+     * Returns the name of the line taken.
+     * @return the name of the line
+     */
     public String getLine() {
         return this.line;
     }

src/main/java/fr/u_paris/gla/project/itinerary/Stop.java

@@ -5,6 +5,10 @@ import fr.u_paris.gla.project.utils.GPS;
 import java.util.HashSet;
 import java.util.Set;
 
+/**
+ * A representation of a stop used as a node
+ * for the path-finding algorithm.
+ */
 public class Stop {
     // The total number of stops
     private static int counter = 0;
@@ -25,6 +29,12 @@ public class Stop {
     //Maximal speed in m/s
     private final double MAX_SPEED = 14.;
 
+    /**
+     * @param line the line passing through the stop
+     * @param name the name of the stop
+     * @param latitude the latitude of the stop in decimal degrees (DD)
+     * @param longitude the longitude of the stop in DD
+     */
     public Stop(String line, String name, double latitude, double longitude) {
         lines = new HashSet<>();
         lines.add(line);
@@ -44,6 +54,11 @@ public class Stop {
         return id;
     }
 
+    /**
+     * Computes the heuristic cost of the node relative to the goal node
+     * @param goalNode the node we're trying to reach
+     * @return the heuristic cost
+     */
     public double getHeuristicCost(Stop goalNode) {
         double distance = GPS.distance(this.latitude, this.longitude, goalNode.latitude, goalNode.longitude);
         return distance/MAX_SPEED;
@@ -65,21 +80,41 @@ public class Stop {
         this.f = value;
     }
 
+    /**
+     * Returns the name of the stop
+     * @return the name of the stop
+     */
     public String getName(){
         return name;
     }
 
+    /**
+     * Returns latitude of the stop
+     * @return stop latitude in DD
+     */
     public double getLatitude(){
         return latitude;
     }
 
+    /**
+     * Returns longitude of the stop
+     * @return stop longitude in DD
+     */
     public double getLongitude(){
         return longitude;
     }
 
+    /**
+     * Add a transport line to the stop
+     * @param s the line to add
+     */
     public void addLine(String s){
         lines.add(s);
     }
 
+    /**
+     * Returns the lines
+     * @return all transport lines passing through this stop.
+     */
     public Set<String> getLines() { return this.lines; }
 }