Apply review feedback

application/src/main/java/org/opentripplanner/graph_builder/module/StreetLinkerModule.java

@@ -129,8 +129,8 @@ public void linkTransitStops(Graph graph, TimetableRepository timetableRepositor
 
   /**
    * Determines if a given transit stop vertex is already linked to the street network, taking into
-   * account that flex stop need special linking to both a walkable and drivable edge. For example,
-   * the {@link OsmBoardingLocationsModule}, which runs before this one, links stops often to
+   * account that flex stops need special linking to both a walkable and drivable edge. For example,
+   * the {@link OsmBoardingLocationsModule}, which runs before this one, often links stops to
    * walkable edges only.
    *
    * @param stopVertex The transit stop vertex to be checked.

application/src/test/java/org/opentripplanner/graph_builder/module/StreetLinkerModuleTest.java

@@ -122,14 +122,23 @@ void linkFlexStopWithBoardingLocation() {
       // stop is used by a flex trip, needs to be linked to both the walk and car edge,
       // also linked to the boarding location
       assertThat(model.stopVertex().getOutgoing()).hasSize(3);
+
+      // while the order of the link doesn't matter, it _is_ deterministic.
+      // first we have the link to the boarding location where the passengers are expected
+      // to wait.
       var links = model.outgoingLinks();
       assertInstanceOf(BoardingLocationToStopLink.class, links.getFirst());
+
+      // the second link is the link to the walkable street network. this is not really necessary
+      // because the boarding location is walkable. this will be refactored away in the future.
       var linkToWalk = links.get(1);
       SplitterVertex walkSplit = (SplitterVertex) linkToWalk.getToVertex();
 
       assertTrue(walkSplit.isConnectedToWalkingEdge());
       assertFalse(walkSplit.isConnectedToDriveableEdge());
 
+      // lastly we have the link to the drivable street network because vehicles also need to
+      // reach the stop if it's part of a flex trip.
       var linkToCar = links.getLast();
       SplitterVertex carSplit = (SplitterVertex) linkToCar.getToVertex();