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

@@ -40,8 +40,8 @@ public final class ScheduledTripTimes implements TripTimes {
   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,18 +53,25 @@ public final class ScheduledTripTimes implements TripTimes {
   private final List<BookingInfo> dropOffBookingInfos;
   private final List<BookingInfo> pickupBookingInfos;
 
+  /**
+   * The headsign displayed by the vehicle at each stop along this trip. The array index is the
+   * stop index within this trip's TripPattern. 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;
 
+  /** TODO RT_AB: document, what is this for? */
   private final int[] originalGtfsStopSequence;
 
   ScheduledTripTimes(ScheduledTripTimesBuilder builder) {

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;
@@ -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

@@ -139,11 +139,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);