more javadoc

src/main/java/fr/u_paris/gla/project/App.java

@@ -63,7 +63,7 @@ public class App {
         }
     }
 
-    /** @param out */
+    /** @param out the output stream */
     public static void printAppInfos(PrintStream out) {
         Properties props = new Properties();
         try (InputStream is = App.class.getResourceAsStream("application.properties")) { //$NON-NLS-1$

src/main/java/fr/u_paris/gla/project/idfm/CSVStreamProvider.java

@@ -18,9 +18,18 @@ import java.util.Set;
 import fr.u_paris.gla.project.io.NetworkFormat;
 import fr.u_paris.gla.project.utils.GPS;
 
+/**
+ * CSV Stream Provider class
+ */
 public final class CSVStreamProvider {
+    /**
+     * Formatter from numbers into GPS Coordinates
+     */
     private static final NumberFormat GPS_FORMATTER            = NetworkFormat
             .getGPSFormatter();
+    /**
+     * Formatter from numbers into MM:SS
+     */
     private static final NumberFormat MINUTES_SECOND_FORMATTER = NumberFormat
             .getInstance(Locale.ENGLISH);
     static {
@@ -28,6 +37,9 @@ public final class CSVStreamProvider {
     }
     /** Number of seconds in a minute. */
     private static final int  SECONDS_IN_MINUTES = 60;
+    /**
+     * Number of seconds in an hour
+     */
     private static final long SECONDS_IN_HOURS   = 3_600;
     // Magically chosen values
     /** Maximal speed in km/h */
@@ -35,25 +47,59 @@ public final class CSVStreamProvider {
     /** Distance to reach maximal speed in km */
     private static final double TWO_ACCELERATION_DISTANCE = 0.2;
 
+    /**
+     * Current CSV Line
+     */
     private String[] line = new String[NetworkFormat.NUMBER_COLUMNS];
 
+    /**
+     * Current CSV transport line iterator
+     */
     private Iterator<TraceEntry>      currentTrace;
+    /**
+     * Current Stop path iterator
+     */
     private Iterator<List<StopEntry>> currentPath         = Collections.emptyIterator();
+    /**
+     * current iterator for the begin of the line
+     */
     private Iterator<StopEntry>       currentSegmentStart = Collections.emptyIterator();
+    /**
+     * current iterator for the end of the line
+     */
     private Iterator<StopEntry>       currentSegmentEnd   = Collections.emptyIterator();
+    /**
+     * HashMap of the current line's segments
+     */
     Map<StopEntry, Set<StopEntry>>    lineSegments        = new HashMap<>();
 
+    /**
+     * current begin of line
+     */
     private StopEntry start = null;
+    /**
+     * current end of line
+     */
     private StopEntry end   = null;
 
+    /**
+     * csv stream iterator checker
+     */
     private boolean hasNext = false;
+    /**
+     * tells if we're already on the next
+     */
     private boolean onNext  = false;
 
-    /** Create the stream provider */
+    /** Create the stream provider
+     *  @param traces an iterator of the possible traces */
     public CSVStreamProvider(Iterator<TraceEntry> traces) {
         this.currentTrace = traces;
     }
 
+    /** Method that tells if we have segments or paths to go through
+     * @return if there are next elements or not
+     */
     public boolean hasNext() {
         if (!this.onNext) {
             skipToNext();
@@ -61,6 +107,9 @@ public final class CSVStreamProvider {
         return this.hasNext;
     }
 
+    /**
+     * Skip to either the next segment or the next path
+     */
     private void skipToNext() {
         if (this.onNext) {
             return;
@@ -76,6 +125,9 @@ public final class CSVStreamProvider {
         }
     }
 
+    /**
+     * Skips to the next segment
+     */
     private void skipToNextNewSegment() {
         do {
             this.start = this.currentSegmentStart.next();
@@ -115,6 +167,9 @@ public final class CSVStreamProvider {
         } while (currentSegmentStart == null);
     }
 
+    /** Store current trace' data as a String array
+     * @return The newly generated line of text
+     */
     public String[] next() {
         if (!this.onNext) {
             skipToNext();
@@ -135,9 +190,10 @@ public final class CSVStreamProvider {
         return Arrays.copyOf(this.line, this.line.length);
     }
 
-    /** @param stop1
-     * @param nextLine
-     * @param i */
+    /** creates adds a station into the next line String
+     * @param stop  the stop
+     * @param nextLine the next line
+     * @param index the stop index in the next line */
     private static void fillStation(StopEntry stop, String[] nextLine, int index) {
         nextLine[index] = stop.lname;
         nextLine[index + 1] = MessageFormat.format("{0}, {1}", //$NON-NLS-1$
@@ -146,8 +202,9 @@ public final class CSVStreamProvider {
 
     }
 
-    /** @param distanceToTime
-     * @return */
+    /** turns a number into a formatted time string
+     * @param time the time value
+     * @return the time as a String */
     private static String formatTime(long time) {
         return MessageFormat.format("{0}:{1}", //$NON-NLS-1$
                 MINUTES_SECOND_FORMATTER.format(time / SECONDS_IN_MINUTES), MINUTES_SECOND_FORMATTER.format(time % SECONDS_IN_MINUTES));

src/main/java/fr/u_paris/gla/project/idfm/CSVStreamSchedulesProvider.java

@@ -13,6 +13,9 @@ import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * the CSV Stream Provider (for the Schedules)
+ */
 public class CSVStreamSchedulesProvider {
     private static final NumberFormat MINUTES_SECOND_FORMATTER = NumberFormat
             .getInstance(Locale.ENGLISH);

src/main/java/fr/u_paris/gla/project/idfm/IDFMNetworkExtractor.java

@@ -34,30 +34,63 @@ public class IDFMNetworkExtractor {
     private static final Logger LOGGER = Logger
             .getLogger(IDFMNetworkExtractor.class.getName());
 
+    /**
+     * the URL of the Trace CSV
+     */
     // IDF mobilite API URLs
     private static final String TRACE_FILE_URL = "https://data.iledefrance-mobilites.fr/api/explore/v2.1/catalog/datasets/traces-des-lignes-de-transport-en-commun-idfm/exports/csv?lang=fr&timezone=Europe%2FBerlin&use_labels=true&delimiter=%3B";
+    /**
+     * The URL of the Stops CSV
+     */
     private static final String STOPS_FILE_URL = "https://data.iledefrance-mobilites.fr/api/explore/v2.1/catalog/datasets/arrets-lignes/exports/csv?lang=fr&timezone=Europe%2FBerlin&use_labels=true&delimiter=%3B";
 
+    /**
+     * the index in the CSV of a Trace's ID
+     */
     // IDF mobilite csv formats
     private static final int IDFM_TRACE_ID_INDEX = 0;
+    /**
+     * the index in the CSV of a Trace's Name
+     */
     private static final int IDFM_TRACE_SNAME_INDEX = 1;
+    /**
+     * the index in the CSV of a Trace's shape
+     */
     private static final int IDFM_TRACE_SHAPE_INDEX = 6;
 
+    /**
+     * The index in the CSV of the Stops' id
+     */
     private static final int IDFM_STOPS_RID_INDEX = 0;
+    /**
+     * The index in the CSV of the Stops' schedules
+     */
     private static final int IDFM_STOPS_SCHEDULES_INDEX = 3;
+    /**
+     * The index in the CSV of the Stops' names
+     */
     private static final int IDFM_STOPS_NAME_INDEX = 5;
+    /**
+     * The index in the CSV of the Stops' longitude
+     */
     private static final int IDFM_STOPS_LON_INDEX = 6;
+    /**
+     * The index in the CSV of the Stops' latitude
+     */
     private static final int IDFM_STOPS_LAT_INDEX = 7;
 
     // Magically chosen values
     /** A number of stops on each line */
     private static final int GUESS_STOPS_BY_LINE = 5;
 
+    /**
+     * The quarter of a kilometer as a static value
+     */
     // Well named constants
     private static final double QUARTER_KILOMETER = .25;
 
     /**
-     * Main entry point for the extractor of IDF mobilite data into a network as
+     * Main entry point for the extractor of IDF mobilité data into a network as
      * defined by this application.
      *
      * @param args
@@ -115,6 +148,9 @@ public class IDFMNetworkExtractor {
         }
     }
 
+    /** Clean the traces/remove the unresolved lines
+     * @param traces  the traces to clean
+     */
     private static void cleanTraces(Map<String, TraceEntry> traces) {
         Set<String> toRemove = new HashSet<>();
         for (Entry<String, TraceEntry> traceEntry : traces.entrySet()) {
@@ -131,7 +167,9 @@ public class IDFMNetworkExtractor {
         }
     }
 
-    /** @param path */
+    /** Tells if the current trasport line has all its stops entries resolved
+     * @param stops the stops list
+     * @return if the line is "clean"*/
     private static boolean cleanLine(List<List<StopEntry>> stops) {
         for (List<StopEntry> path : stops) {
             for (int i = 0; i < path.size(); i++) {
@@ -150,6 +188,11 @@ public class IDFMNetworkExtractor {
         return true;
     }
 
+    /** adds a stop to all related variables
+     * @param line  the transport line involved with the new stop
+     * @param traces the traces related to it
+     * @param stops the general stops list
+     */
     private static void addStop(String[] line, Map<String, TraceEntry> traces,
             List<StopEntry> stops) {
         StopEntry entry = new StopEntry(line[IDFM_STOPS_NAME_INDEX],
@@ -167,6 +210,10 @@ public class IDFMNetworkExtractor {
         stops.add(entry);
     }
 
+    /** add a line to the related list of traces
+     * @param line the line as a string
+     * @param traces the traces
+     */
     private static void addLine(String[] line, Map<String, TraceEntry> traces) {
         TraceEntry entry = new TraceEntry(line[IDFM_TRACE_SNAME_INDEX]);
         List<List<StopEntry>> buildPaths = buildPaths(line[IDFM_TRACE_SHAPE_INDEX]);
@@ -179,6 +226,11 @@ public class IDFMNetworkExtractor {
         }
     }
 
+    /** add a new entry as a candidate to a trace
+     * @param trace  the trace
+     * @param entry  the entry
+     * @return the trace in question
+     */
     private static TraceEntry addCandidate(TraceEntry trace, StopEntry entry) {
         for (List<StopEntry> path : trace.getPaths()) {
             for (StopEntry stopEntry : path) {
@@ -193,6 +245,10 @@ public class IDFMNetworkExtractor {
         return trace;
     }
 
+    /** turn a JSON list of stops into a list of paths
+     * @param pathsJSON the JSON String of all paths
+     * @return the paths as a List of StopEntries
+     */
     private static List<List<StopEntry>> buildPaths(String pathsJSON) {
         List<List<StopEntry>> all = new ArrayList<>();
         try {
@@ -220,6 +276,10 @@ public class IDFMNetworkExtractor {
         return all;
     }
 
+    /** extract the terminus out of a JSON file
+     * @param JSON the JSON
+     * @return a list of strings related to the terminus
+     */
     private static List<String> extractTerminus(String JSON) {
         List<String> all = new ArrayList<>();
         try {

src/main/java/fr/u_paris/gla/project/io/NetworkFormat.java

@@ -14,8 +14,10 @@ import java.util.Locale;
  * 
  * @author Emmanuel Bigeon */
 public final class NetworkFormat {
-
+    /** The amount of columns in the CSV file */
     public static final int NUMBER_COLUMNS = 8;
+
+    /** The amount of decimal places in the GPS' coordinates */
     public static final int GPS_PRECISION  = 18;
 
     /** The index of the line name in the network format */
@@ -45,11 +47,19 @@ public final class NetworkFormat {
         // Tool class
     }
 
+    /** Convert a {@link java.lang.String} into a {@link java.time.Duration}
+     * @param duration the {@link java.lang.String}
+     * @return the {@link java.time.Duration} object
+     */
     public static Duration parseDuration(String duration) {
         LocalTime time = LocalTime.parse("00:" + duration, DURATION_FORMATTER);
         return Duration.between(time, ZERO);
     }
 
+    /** Format a {@link java.time.Duration} into a {@link java.lang.String}
+     * @param duration an object of type {@link java.time.Duration}
+     * @return a String that depicts the duration in format MM:SS
+     */
     public static String formatDuration(Duration duration) {
         return Long.toString(duration.toMinutes()) + ":"
                 + DURATION_SECONDS_FORMATTER.format(duration.toSecondsPart());
@@ -57,7 +67,7 @@ public final class NetworkFormat {
 
     /** Get a formatter for the numbers in a GPS coordinate pair
      * 
-     * @return the formatter for numbers in a GPS coordinate pair */
+     * @return the {@link java.text.NumberFormat} formatter for numbers in a GPS coordinate pair */
     public static NumberFormat getGPSFormatter() {
         NumberFormat instance = NumberFormat.getNumberInstance(Locale.ENGLISH);
         instance.setMaximumFractionDigits(GPS_PRECISION);

src/main/java/fr/u_paris/gla/project/io/ScheduleFormat.java

@@ -13,11 +13,16 @@ import java.util.List;
  * @author Emmanuel Bigeon
  */
 public final class ScheduleFormat {
+    /** The amount of columns in the CSV file */
     public static final int NUMBER_COLUMNS = 4;
 
+    /** The index of the line name in the schedule format */
     public static final int LINE_INDEX = 0;
+    /** The index of the trip sequence in the schedule format */
     public static final int TRIP_SEQUENCE_INDEX = 1;
+    /** The index of the terminus name in the schedule format */
     public static final int TERMINUS_INDEX = 2;
+    /** The index of the time in the schedule format */
     public static final int TIME_INDEX = 3;
 
     /** Hidden constructor for tool class */
@@ -37,6 +42,9 @@ public final class ScheduleFormat {
         throw new RuntimeException("Not implemented yet");
     }
 
+    /** Create a {@link java.time.format.DateTimeFormatter} object used to format Dates
+     * @return the formatter
+     */
     public static DateTimeFormatter getTimeFormatter() {
         return DateTimeFormatter.ofPattern("HH:mm").withResolverStyle(ResolverStyle.LENIENT);
     }

src/main/java/fr/u_paris/gla/project/utils/CSVTools.java

@@ -32,6 +32,11 @@ public final class CSVTools {
         // Tool class
     }
 
+    /** get a CSV file from a URL, download and parse it, and keep values in memory
+     * @param url the address of the CSV file
+     * @param contentLineConsumer the variable used to store the data
+     * @throws IOException if it's impossible to download the file
+     */
     public static void readCSVFromURL(String url, Consumer<String[]> contentLineConsumer)
             throws IOException {
         ICSVParser parser = new CSVParserBuilder().withSeparator(';').build();
@@ -52,6 +57,11 @@ public final class CSVTools {
         }
     }
 
+    /** Save our current CSV variable's data into an actual file
+     * @param filename the saved file's name and path
+     * @param contentLineConsumer our data variable
+     * @throws IOException if we can't write the data into the file
+     */
     public static void writeCSVToFile(String filename,
             Stream<String[]> contentLineConsumer) throws IOException {
         try (FileWriter writer = new FileWriter(filename, StandardCharsets.UTF_8)) {