Update schema documentation based on review

Author: optionsome

application/src/main/java/org/opentripplanner/apis/transmodel/model/EnumTypes.java

@@ -466,17 +466,19 @@ public class EnumTypes {
 
   public static final GraphQLEnumType VIA_LOCATION_TYPE = GraphQLEnumType.newEnum()
     .name("ViaLocationType")
+    .description("Categorization for via locations.")
     .value(
       "passThrough",
       ViaLocationType.PASS_THROUGH,
-      "Stop location must be " +
-      "visited on-board a transit vehicle or the journey must alight or board at the location."
+      "The via stop location must be visited as part of a transit trip as at the " +
+      "boarding stop, the intermediate stop, or the alighting stop."
     )
     .value(
       "visit",
       ViaLocationType.VISIT,
-      "Location is a stop location where the " +
-      "passenger boards a vehicle or alights from a vehicle, or a coordinate which is visited."
+      "The location is visited physically by boarding or alighting a transit trip at " +
+      "a given stop, or by traveling to a requested coordinate location. Intermediate stops " +
+      "visited on-board do not count."
     )
     .build();
 

application/src/main/java/org/opentripplanner/apis/transmodel/model/plan/PlanPlaceType.java

@@ -136,8 +136,8 @@ public static GraphQLObjectType create(
           .name("viaLocationType")
           .type(EnumTypes.VIA_LOCATION_TYPE)
           .description(
-            "If this place was used as a via location in the request, this defines " +
-            "what type of a via location this place is."
+            "This defines if the place is a requested via location, and what kind it is. If the " +
+            "value is `null`, this place is not a via location."
           )
           .dataFetcher(environment -> ((Place) environment.getSource()).viaLocationType)
           .build()

application/src/main/resources/org/opentripplanner/apis/gtfs/schema.graphqls

@@ -1105,8 +1105,8 @@ type Place {
   """
   vertexType: VertexType @deprecated(reason : "Unmaintained. Use `stop`, `rentalVehicle`, `vehicleParking` or `vehicleRentalStation` to tell which type it is.") @timingData
   """
-  If this place was used as a via location in the request, this defines what type of a via location
-  this place is.
+  This defines if the place is a requested via location, and what kind it is. If the value is
+  `null`, this place is not a via location.
   """
   viaLocationType: ViaLocationType
 }
@@ -3930,13 +3930,13 @@ enum VertexType {
 "Categorization for via locations."
 enum ViaLocationType {
   """
-  Stop location must be visited on-board a transit vehicle or the journey must alight or board at
-  the location.
+  The via stop location must be visited as part of a transit trip as at the boarding stop, the
+  intermediate stop, or the alighting stop.
   """
   PASS_THROUGH
   """
-  Location is a stop location where the passenger boards a vehicle or alights from a vehicle,
-  or a coordinate which is visited.
+  The location is visited physically by boarding or alighting a transit trip at a given stop, or by
+  traveling to a requested coordinate location. Intermediate stops visited on-board do not count.
   """
   VISIT
 }

application/src/main/resources/org/opentripplanner/apis/transmodel/schema.graphql

@@ -527,7 +527,7 @@ type Place {
   rentalVehicle: RentalVehicle
   "Type of vertex. (Normal, Bike sharing station, Bike P+R, Transit quay) Mostly used for better localization of bike sharing and P+R station names"
   vertexType: VertexType
-  "If this place was used as a via location in the request, this defines what type of a via location this place is."
+  "This defines if the place is a requested via location, and what kind it is. If the value is `null`, this place is not a via location."
   viaLocationType: ViaLocationType
 }
 
@@ -2081,10 +2081,11 @@ enum VertexType {
   transit
 }
 
+"Categorization for via locations."
 enum ViaLocationType {
-  "Stop location must be visited on-board a transit vehicle or the journey must alight or board at the location."
+  "The via stop location must be visited as part of a transit trip as at the boarding stop, the intermediate stop, or the alighting stop."
   passThrough
-  "Location is a stop location where the passenger boards a vehicle or alights from a vehicle, or a coordinate which is visited."
+  "The location is visited physically by boarding or alighting a transit trip at a given stop, or by traveling to a requested coordinate location. Intermediate stops visited on-board do not count."
   visit
 }