rename field to match interface accessor method

also moved javadoc to interfaces instead of impl
in response to PR review

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

@@ -34,6 +34,7 @@ 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.
    */
@@ -54,9 +55,8 @@ public final class ScheduledTripTimes implements TripTimes {
   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.
+   * Any number of array elements may point to the same I18NString instance if the headsign remains
+   * unchanged between stops.
    */
   @Nullable
   private final I18NString[] headsigns;
@@ -71,8 +71,8 @@ public final class ScheduledTripTimes implements TripTimes {
   @Nullable
   private final String[][] headsignVias;
 
-  /** This is for matching stops with external services, in the realtime-updaters for example. */
-  private final int[] originalGtfsStopSequence;
+  /** @see TripTimes#gtfsSequenceOfStopIndex(int) */
+  private final int[] gtfsSequenceOfStopIndex;
 
   ScheduledTripTimes(ScheduledTripTimesBuilder builder) {
     this.timeShift = builder.timeShift();
@@ -85,7 +85,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();
   }
 
@@ -114,7 +114,7 @@ public ScheduledTripTimesBuilder copyOf(Deduplicator deduplicator) {
       pickupBookingInfos,
       headsigns,
       headsignVias,
-      originalGtfsStopSequence,
+      gtfsSequenceOfStopIndex,
       deduplicator
     );
   }
@@ -279,16 +279,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

@@ -58,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)

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