Merge pull request opentripplanner#6803 from Aubin-MaaS/free-edge

add comment and documentation on FreeEdge

Author: leonardehrenfried

application/src/main/java/org/opentripplanner/street/model/edge/FreeEdge.java

@@ -1,14 +1,12 @@
 package org.opentripplanner.street.model.edge;
 
-import org.locationtech.jts.geom.LineString;
 import org.opentripplanner.framework.i18n.I18NString;
 import org.opentripplanner.street.model.vertex.Vertex;
 import org.opentripplanner.street.search.state.State;
 import org.opentripplanner.street.search.state.StateEditor;
 
 /**
- * An edge that costs nothing to traverse. Used for connecting intersection vertices to the main
- * edge-based graph.
+ * An edge that has a trivial cost to traverse.
  *
  * @author novalis
  */
@@ -25,6 +23,9 @@ public static FreeEdge createFreeEdge(Vertex from, Vertex to) {
   @Override
   public State[] traverse(State s0) {
     StateEditor s1 = s0.edit(this);
+    // This edge is used to connect vertices not on the street network, such as origin, destination
+    // and station centroids, onto the street network. By adding a small cost, we prevent a normal
+    // street search from going via these vertices.
     s1.incrementWeight(1);
     s1.setBackMode(null);
     return s1.makeStateArray();

application/src/main/java/org/opentripplanner/street/model/edge/TemporaryFreeEdge.java

@@ -5,6 +5,9 @@
 import org.opentripplanner.street.search.state.State;
 import org.opentripplanner.street.search.state.StateEditor;
 
+/**
+ * A temporary edge which links the origin / destination of a street search to the street graph.
+ */
 public class TemporaryFreeEdge extends FreeEdge implements TemporaryEdge {
 
   private TemporaryFreeEdge(TemporaryVertex from, Vertex to) {
@@ -26,6 +29,7 @@ public static TemporaryFreeEdge createTemporaryFreeEdge(Vertex from, TemporaryVe
   @Override
   public State[] traverse(State s0) {
     StateEditor s1 = s0.edit(this);
+    // a small cost is added to prevent other searches going through this temporary edge
     s1.incrementWeight(1);
     s1.setBackMode(null);