DOC: 134 - Add more documentation to transfer methods in converter.

src/main/java/ch/naviqore/service/gtfs/raptor/convert/GtfsToRaptorConverter.java

@@ -86,18 +86,25 @@ private void addRoute(GtfsRoutePartitioner.SubRoute subRoute) {
     }
 
     /**
-     * Processes all transfers including additional transfers, parent-child transfers, and GTFS transfers, ensuring
-     * proper precedence between them.
+     * Processes all types of transfers, ensuring the correct order of precedence:
+     * <p>
+     * 1. Additional transfers: These transfers have the lowest priority and are processed first.
+     * 2. Parent-child derived transfers: If a transfer is defined between two parent stops (e.g., A to B), this method
+     * derives corresponding transfers for their child stops (e.g., A1, A2, ... to B1, B2, ...).
+     * 3. GTFS schedule-defined transfers: Transfers explicitly defined in the GTFS schedule (e.g., A1 to B2) take the
+     * highest priority and are applied last, thereby overwriting transfers previously derived from parent stops.
+     * <p>
+     * The method ensures that all transfers, whether additional, derived, or explicitly defined, are handled in the
+     * correct priority order.
      */
     private void processAllTransfers() {
         addAdditionalTransfers();
         processStopAndParentChildTransfers();
-        addGTFSTransfersWithPrecedence();
+        addGtfsTransfersWithPrecedence();
     }
 
     /**
-     * Adds all additional transfers, these have the lowest priority and will be overwritten either by parent-child
-     * transfers derived from GTFS transfers and explicit GTFS transfers (if present).
+     * Adds all additional transfers.
      */
     private void addAdditionalTransfers() {
         for (TransferGenerator.Transfer transfer : additionalTransfers) {
@@ -106,8 +113,7 @@ private void addAdditionalTransfers() {
     }
 
     /**
-     * Processes transfers for each stop and handles parent-child relationships. These will later be overwritten, if
-     * explicit transfers between stops are defined in the GTFS schedule.
+     * Processes transfers for each stop and handles parent-child relationships.
      */
     private void processStopAndParentChildTransfers() {
         for (String stopId : addedStops) {
@@ -118,41 +124,55 @@ private void processStopAndParentChildTransfers() {
 
     /**
      * Processes parent and child transfers for a given stop, ensuring proper precedence.
+     * <p>
+     * Assuming transfers A-A, A-B are defined, and both stops are parent stops with 2 children (A1, A2, B1, B2) and
+     * there are also active departures on the parent stop B. For stop A1 following transfers will be derived: (A-A):
+     * A1-A1, A1-A2, (A-B): A1-B, A1-B1, A1-B2
+     * <p>
+     * Alternatively, this method can also handle the case when parent stops have departures but no transfers specified.
+     * For example if transfers A1-A2, A1-B1 are defined, following transfers for stop A may be derived: (A1-A2): A-A,
+     * A-A1, A-A2, (A1-B1): A-B, A-B1, A-B2.
      *
      * @param stop the stop for which parent and child transfers are being processed
      */
     private void processParentAndChildTransfersForStop(Stop stop) {
-        // Handle parent transfers
-        stop.getParent().ifPresent(parentStop -> deriveAllTransfersFromStop(stop, parentStop));
+        // this checks if parent stop is present (i.e. checks if stop in question is child stop) and if true, will
+        // derive apply all parent transfers to child stop.
+        stop.getParent().ifPresent(parentStop -> applyTransfersFromOtherStop(stop, parentStop));
 
-        // Handle child transfers for each child of the current stop
+        // alternatively, if stop in question is parent stop, all transfers from child stops to other stops should also
+        // be applied to parent stop.
         for (Stop childStop : stop.getChildren()) {
-            deriveAllTransfersFromStop(stop, childStop);
+            applyTransfersFromOtherStop(stop, childStop);
         }
 
-        // Handle direct transfers for the stop
-        addDirectStopTransfers(stop);
+        // this is used to make sure that all to stop children/parents are also included for transfer defined on the
+        // current stop.
+        addToStopChildrenTransfers(stop);
     }
 
     /**
-     * This method expands transfers defined on parent stops to all children stops linked to the transfer.
+     * This method gets all possible transfers from the provider stop and adds copies for the consumer stop. E.g. if A1
+     * is the consumer stop, A is the provider stop and A has a transfer to B (A-B), this method will create the
+     * transfer A1-B and potentially A1-B1, A1-B2,... if B has child stops.
      *
-     * @param fromStop the stop of interest, which transfers should be derived for
-     * @param toStop   the parent or child stop to process transfers for
+     * @param consumerStop the stop of interest where transfers should be derived for
+     * @param providerStop the stop from which transfers should be derived from for the consumerStop
      */
-    private void deriveAllTransfersFromStop(Stop fromStop, Stop toStop) {
-        Collection<TransferGenerator.Transfer> transfers = collectTransfersBetweenStops(fromStop, toStop);
+    private void applyTransfersFromOtherStop(Stop consumerStop, Stop providerStop) {
+        Collection<TransferGenerator.Transfer> transfers = expandTransfersFromStop(providerStop);
         for (TransferGenerator.Transfer transfer : transfers) {
-            builder.addTransfer(transfer.from().getId(), transfer.to().getId(), transfer.duration());
+            builder.addTransfer(consumerStop.getId(), transfer.to().getId(), transfer.duration());
         }
     }
 
     /**
-     * Adds direct transfers for a stop, ensuring minimum transfer time is handled correctly.
+     * Adds transfers to all children stops of all transfer destinations. E.g. if stop B has stops B1 and B2 as children
+     * and stop A has transfer A-B defined, this method will newly create transfers A-B1, A-B2.
      *
-     * @param stop the stop to process direct transfers for
+     * @param stop the stop to process all to stops for
      */
-    private void addDirectStopTransfers(Stop stop) {
+    private void addToStopChildrenTransfers(Stop stop) {
         for (Transfer stopTransfer : stop.getTransfers()) {
             if (stopTransfer.getTransferType() == TransferType.MINIMUM_TIME && stopTransfer.getMinTransferTime()
                     .isPresent()) {
@@ -166,7 +186,7 @@ private void addDirectStopTransfers(Stop stop) {
     }
 
     /**
-     * Adds GTFS transfers, ensuring precedence over additional transfers.
+     * Adds transfers explicitly defined in the GTFS schedule, ensuring precedence over additional transfers.
      */
     private void addGtfsTransfersWithPrecedence() {
         for (String stopId : addedStops) {
@@ -182,29 +202,34 @@ private void addGtfsTransfersWithPrecedence() {
     }
 
     /**
-     * Collects transfers between a parent stop and a child stop, ensuring precedence of explicit transfers.
+     * Collects all possible transfers from a given stop. This method loops over all the stops transfers and checks if
+     * the "to stops" have any children and parents and adds transfers to those if needed. For example if Stop A has the
+     * following transfers: A-A1 (A1 is child of A), A-A (note A has also a child A2), A-B (B has B1, B2 as children)
+     * and A-B1. This method will return all the previously defined transfers: A-A1, A-A, A-B and A-B1 and derive the
+     * following: A-A2, A-B2. Note: even though A-A1 and A-B1 could be derived from A-A and A-B, those are not added
+     * because these were already explicitly defined.
      *
-     * @param fromStop   the originating stop
-     * @param parentStop the parent or child stop to collect transfers for
-     * @return a collection of transfers between the stops
+     * @param stop the stop of interest
+     * @return a collection of complete transfers from stop
      */
-    private Collection<TransferGenerator.Transfer> collectTransfersBetweenStops(Stop fromStop, Stop parentStop) {
+    private Collection<TransferGenerator.Transfer> expandTransfersFromStop(Stop stop) {
         Map<Stop, TransferGenerator.Transfer> parentTransfers = new HashMap<>();
+        // to ensure explicitly defined transfers take precedence, those are collected separately and applied in the
+        // end, potentially overwriting other lower priority transfers
         List<TransferGenerator.Transfer> otherTransfers = new ArrayList<>();
 
-        for (Transfer transfer : parentStop.getTransfers()) {
+        for (Transfer transfer : stop.getTransfers()) {
             if (transfer.getTransferType() != TransferType.MINIMUM_TIME || transfer.getMinTransferTime().isEmpty()) {
                 continue;
             }
             Stop toStop = transfer.getToStop();
             if (addedStops.contains(toStop.getId())) {
-                otherTransfers.add(
-                        new TransferGenerator.Transfer(fromStop, toStop, transfer.getMinTransferTime().get()));
+                otherTransfers.add(new TransferGenerator.Transfer(stop, toStop, transfer.getMinTransferTime().get()));
             }
             for (Stop childToStop : toStop.getChildren()) {
                 if (addedStops.contains(childToStop.getId())) {
                     parentTransfers.put(childToStop,
-                            new TransferGenerator.Transfer(fromStop, childToStop, transfer.getMinTransferTime().get()));
+                            new TransferGenerator.Transfer(stop, childToStop, transfer.getMinTransferTime().get()));
                 }
             }
         }