Additional SVG diagrams in updaters package.md

src/main/java/org/opentripplanner/model/TripTimeOnDate.java

@@ -220,6 +220,7 @@ public I18NString getHeadsign() {
     return tripTimes.getHeadsign(stopIndex);
   }
 
+  /** @return a list of via names visible at this stop, or an empty list if there are no vias. */
   public List<String> getHeadsignVias() {
     return tripTimes.getHeadsignVias(stopIndex);
   }

src/main/java/org/opentripplanner/transit/model/timetable/RealTimeTripTimes.java

@@ -98,13 +98,6 @@ public I18NString getHeadsign(final int stop) {
       : scheduledTripTimes.getHeadsign(stop);
   }
 
-  /**
-   * Return list of via names per particular stop. This field provides info about intermediate stops
-   * between current stop and final trip destination. Mapped from NeTEx DestinationDisplay.vias. No
-   * GTFS mapping at the moment.
-   *
-   * @return Empty list if there are no vias registered for a stop.
-   */
   @Override
   public List<String> getHeadsignVias(final int stop) {
     return scheduledTripTimes.getHeadsignVias(stop);

src/main/java/org/opentripplanner/transit/model/timetable/ScheduledTripTimes.java

@@ -34,14 +34,15 @@ public final class ScheduledTripTimes implements TripTimes {
    * When time-shifting from one time-zone to another negative times may occur.
    */
   private static final int MIN_TIME = DurationUtils.durationInSeconds("-12h");
+
   /**
    * We allow a trip to last for maximum 20 days. In Norway the longest trip is 6 days.
    */
   private static final int MAX_TIME = DurationUtils.durationInSeconds("20d");
 
   /**
-   * Implementation notes: This allows re-using the same scheduled arrival and departure time
-   * arrays for many ScheduledTripTimes. It is also used in materializing frequency-based
+   * Implementation notes: This timeShift allows re-using the same scheduled arrival and departure
+   * time arrays for many ScheduledTripTimes. It is also used in materializing frequency-based
    * ScheduledTripTimes.
    */
   private final int timeShift;
@@ -53,19 +54,24 @@ public final class ScheduledTripTimes implements TripTimes {
   private final List<BookingInfo> dropOffBookingInfos;
   private final List<BookingInfo> pickupBookingInfos;
 
+  /**
+   * Any number of array elements may point to the same I18NString instance if the headsign remains
+   * unchanged between stops.
+   */
   @Nullable
   private final I18NString[] headsigns;
 
   /**
-   * Implementation notes: This is 2D array since there can be more than one via name/stop per each
-   * record in stop sequence). Outer array may be null if there are no vias in stop sequence. Inner
-   * array may be null if there are no vias for particular stop. This is done in order to save
-   * space.
+   * A 2D array of String containing zero or more Via messages displayed at each stop in the
+   * stop sequence. This reference be null if no stop in the entire sequence of stops has any via
+   * strings. Any subarray may also be null or empty if no Via strings are displayed at that
+   * particular stop. These nulls are allowed to conserve memory in the common case where there are
+   * few or no via messages.
    */
   @Nullable
   private final String[][] headsignVias;
 
-  private final int[] originalGtfsStopSequence;
+  private final int[] gtfsSequenceOfStopIndex;
 
   ScheduledTripTimes(ScheduledTripTimesBuilder builder) {
     this.timeShift = builder.timeShift();
@@ -78,7 +84,7 @@ public final class ScheduledTripTimes implements TripTimes {
     this.dropOffBookingInfos = Objects.requireNonNull(builder.dropOffBookingInfos());
     this.headsigns = builder.headsigns();
     this.headsignVias = builder.headsignVias();
-    this.originalGtfsStopSequence = builder.originalGtfsStopSequence();
+    this.gtfsSequenceOfStopIndex = builder.gtfsSequenceOfStopIndex();
     validate();
   }
 
@@ -107,7 +113,7 @@ public ScheduledTripTimesBuilder copyOf(Deduplicator deduplicator) {
       pickupBookingInfos,
       headsigns,
       headsignVias,
-      originalGtfsStopSequence,
+      gtfsSequenceOfStopIndex,
       deduplicator
     );
   }
@@ -272,16 +278,16 @@ public OccupancyStatus getOccupancyStatus(int ignore) {
 
   @Override
   public int gtfsSequenceOfStopIndex(final int stop) {
-    return originalGtfsStopSequence[stop];
+    return gtfsSequenceOfStopIndex[stop];
   }
 
   @Override
   public OptionalInt stopIndexOfGtfsSequence(int stopSequence) {
-    if (originalGtfsStopSequence == null) {
+    if (gtfsSequenceOfStopIndex == null) {
       return OptionalInt.empty();
     }
-    for (int i = 0; i < originalGtfsStopSequence.length; i++) {
-      var sequence = originalGtfsStopSequence[i];
+    for (int i = 0; i < gtfsSequenceOfStopIndex.length; i++) {
+      var sequence = gtfsSequenceOfStopIndex[i];
       if (sequence == stopSequence) {
         return OptionalInt.of(i);
       }

src/main/java/org/opentripplanner/transit/model/timetable/ScheduledTripTimesBuilder.java

@@ -23,7 +23,7 @@ public class ScheduledTripTimesBuilder {
   private List<BookingInfo> pickupBookingInfos;
   private I18NString[] headsigns;
   private String[][] headsignVias;
-  private int[] originalGtfsStopSequence;
+  private int[] gtfsSequenceOfStopIndex;
   private final DeduplicatorService deduplicator;
 
   ScheduledTripTimesBuilder(@Nullable DeduplicatorService deduplicator) {
@@ -41,7 +41,7 @@ public class ScheduledTripTimesBuilder {
     List<BookingInfo> pickupBookingInfos,
     I18NString[] headsigns,
     String[][] headsignVias,
-    int[] originalGtfsStopSequence,
+    int[] gtfsSequenceOfStopIndex,
     DeduplicatorService deduplicator
   ) {
     this.timeShift = timeShift;
@@ -54,7 +54,7 @@ public class ScheduledTripTimesBuilder {
     this.pickupBookingInfos = pickupBookingInfos;
     this.headsigns = headsigns;
     this.headsignVias = headsignVias;
-    this.originalGtfsStopSequence = originalGtfsStopSequence;
+    this.gtfsSequenceOfStopIndex = gtfsSequenceOfStopIndex;
     this.deduplicator = deduplicator == null ? DeduplicatorService.NOOP : deduplicator;
   }
 
@@ -169,12 +169,12 @@ public ScheduledTripTimesBuilder withHeadsignVias(String[][] headsignVias) {
     return this;
   }
 
-  public int[] originalGtfsStopSequence() {
-    return originalGtfsStopSequence;
+  public int[] gtfsSequenceOfStopIndex() {
+    return gtfsSequenceOfStopIndex;
   }
 
-  public ScheduledTripTimesBuilder withOriginalGtfsStopSequence(int[] originalGtfsStopSequence) {
-    this.originalGtfsStopSequence = deduplicator.deduplicateIntArray(originalGtfsStopSequence);
+  public ScheduledTripTimesBuilder withGtfsSequenceOfStopIndex(int[] gtfsSequenceOfStopIndex) {
+    this.gtfsSequenceOfStopIndex = deduplicator.deduplicateIntArray(gtfsSequenceOfStopIndex);
     return this;
   }
 

src/main/java/org/opentripplanner/transit/model/timetable/StopTimeToScheduledTripTimesMapper.java

@@ -4,6 +4,7 @@
 import java.util.BitSet;
 import java.util.Collection;
 import java.util.List;
+import javax.annotation.Nullable;
 import org.opentripplanner.framework.i18n.I18NString;
 import org.opentripplanner.model.StopTime;
 import org.opentripplanner.transit.model.framework.DeduplicatorService;
@@ -57,7 +58,7 @@ private ScheduledTripTimes doMap(Collection<StopTime> stopTimes) {
     builder
       .withDepartureTimes(departures)
       .withArrivalTimes(arrivals)
-      .withOriginalGtfsStopSequence(sequences)
+      .withGtfsSequenceOfStopIndex(sequences)
       .withHeadsigns(makeHeadsignsArray(stopTimes))
       .withHeadsignVias(makeHeadsignViasArray(stopTimes))
       .withDropOffBookingInfos(dropOffBookingInfos)
@@ -103,10 +104,13 @@ private I18NString[] makeHeadsignsArray(final Collection<StopTime> stopTimes) {
   }
 
   /**
-   * Create 2D String array for via names for each stop in sequence.
-   *
-   * @return May be null if no vias are present in stop sequence.
+   * Create 2D array of String containing zero or more Via messages displayed at each stop in the
+   * stop sequence.
+   * @return May be null if no stop in the entire sequence of stops has any via strings. Any
+   * subarray may also be null or empty if no Via strings are displayed at that particular stop.
+   * @see org.opentripplanner.transit.model.timetable.TripTimes#getHeadsignVias(int)
    */
+  @Nullable
   private String[][] makeHeadsignViasArray(final Collection<StopTime> stopTimes) {
     if (
       stopTimes

src/main/java/org/opentripplanner/transit/model/timetable/TripTimes.java

@@ -17,7 +17,8 @@
  * trip times should allow updates and more info, frequency-based trips can use a more compact
  * implementation, and Flex may expose part of the trip as a "scheduled/regular" stop-to-stop
  * trip using this interface. All times are expressed as seconds since midnight (as in
- * GTFS).
+ * GTFS). Unless stated otherwise, accessor methods which take an integer stop parameter refer to
+ * the position within the trip's TripPattern (not its GTFS stop sequence for example).
  */
 public interface TripTimes extends Serializable, Comparable<TripTimes> {
   /**
@@ -129,6 +130,7 @@ default int compareTo(TripTimes other) {
   I18NString getTripHeadsign();
 
   /**
+   * The headsign displayed by the vehicle, which may change at each stop along the trip.
    * Both trip_headsign and stop_headsign (per stop on a particular trip) are optional GTFS fields.
    * A trip may not have a headsign, in which case we should fall back on a Timetable or
    * Pattern-level headsign. Such a string will be available when we give TripPatterns or
@@ -139,11 +141,11 @@ default int compareTo(TripTimes other) {
   I18NString getHeadsign(int stop);
 
   /**
-   * Return list of via names per particular stop. This field provides info about intermediate stops
-   * between current stop and final trip destination. Mapped from NeTEx DestinationDisplay.vias. No
-   * GTFS mapping at the moment.
-   *
-   * @return Empty list if there are no vias registered for a stop.
+   * Vias are an additional intermediate destinations between the given stop and the terminus, which
+   * are displayed alongside the terminus headsign. Vias often change or are displayed only at
+   * certain stops along the way. While the concept of Headsigns exists in both GTFS (Headsign) and
+   * Netex (DestinationDisplay), the Via concept is only present in Transmodel.
+   * @return a list of via names visible at the given stop, or an empty list if there are no vias.
    */
   List<String> getHeadsignVias(int stop);
 
@@ -157,7 +159,7 @@ default int compareTo(TripTimes other) {
   OccupancyStatus getOccupancyStatus(int stop);
 
   /**
-   * Returns the GTFS sequence number of the given 0-based stop position.
+   * Returns the GTFS sequence number of the given 0-based stop position within the pattern.
    * <p>
    * These are the GTFS stop sequence numbers, which show the order in which the vehicle visits the
    * stops. Despite the fact that the StopPattern or TripPattern enclosing this class provides an