docs: clarified wording around route-related fields

PiperOrigin-RevId: 471592585
googleapis · Sep 1, 2022 · 0cb8499 · 0cb8499
1 parent e1b54cd
commit 0cb8499
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 56 deletions.
diff --git a/google/maps/fleetengine/v1/fleetengine.proto b/google/maps/fleetengine/v1/fleetengine.proto
@@ -74,31 +74,31 @@ message TripWaypoint {
   // The role this waypoint plays in this trip, such as pickup or dropoff.
   WaypointType waypoint_type = 3;
 
-  // The path from the previous waypoint to the current waypoint.
+  // The path from the previous waypoint to the current waypoint.  Undefined for
+  // the first waypoint in a list. This field is only populated when requested.
   repeated google.type.LatLng path_to_waypoint = 4;
 
   // The encoded path from the previous waypoint to the current waypoint.
-  // Decoding is not yet supported.
+  //
+  // <p>Note: This field is intended only for use by the Driver SDK and Consumer
+  // SDK. Decoding is not yet supported.
   string encoded_path_to_waypoint = 5;
 
   // The traffic conditions along the path to this waypoint.  Note that traffic
   // is only available for Google Map Platform Rides and Deliveries Solution
   // customers.
   ConsumableTrafficPolyline traffic_to_waypoint = 10;
 
-  // The path distance from the previous waypoint to the current waypoint. If
-  // the waypoint is the first waypoint in the list (e.g.,
-  // `Vehicle.waypoints[0]` or `Trip.remaining_waypoints[0]`), then the value of
-  // this field is undefined.
+  // The path distance from the previous waypoint to the current waypoint.
+  // Undefined for the first waypoint in a list.
   google.protobuf.Int32Value distance_meters = 6;
 
-  // The estimated time of arrival at this waypoint.
+  // The estimated time of arrival at this waypoint. Undefined for the first
+  // waypoint in a list.
   google.protobuf.Timestamp eta = 7;
 
-  // The travel time from previous waypoint to this point. If the waypoint is
-  // the first waypoint in the list (e.g., `Vehicle.waypoints[0]` or
-  // `Trip.remaining_waypoints[0]`), then this value indicates the remaining
-  // time to the waypoint.
+  // The travel time from previous waypoint to this point. Undefined for the
+  // first waypoint in a list.
   google.protobuf.Duration duration = 8;
 }
 

diff --git a/google/maps/fleetengine/v1/trips.proto b/google/maps/fleetengine/v1/trips.proto
@@ -112,60 +112,62 @@ message Trip {
   google.protobuf.Timestamp dropoff_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The full path from the current location to the dropoff point, inclusive.
-  // If this is a shared ride, this path could include waypoints from other
-  // trips.
+  // This path could include waypoints from other trips.
   repeated TripWaypoint remaining_waypoints = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // This field supports manual ordering of the waypoints for the trip.
-  // It contains all of the remaining waypoints of vehicle assigned, as well as
-  // the pickup and drop-off waypoints for this trip.
-  // If the trip hasn't been assigned to a vehicle, then this field is ignored.
-  // For privacy reasons, this field is only populated by the server on
-  // UpdateTrip and CreateTrip calls, and NOT on GetTrip calls.
+  // This field supports manual ordering of the waypoints for the trip. It
+  // contains all of the remaining waypoints for the assigned vehicle, as well
+  // as the pickup and drop-off waypoints for this trip. If the trip hasn't been
+  // assigned to a vehicle, then this field is ignored. For privacy reasons,
+  // this field is only populated by the server on UpdateTrip and CreateTrip
+  // calls, NOT on GetTrip calls.
   repeated TripWaypoint vehicle_waypoints = 20;
 
   // Output only. Anticipated route for this trip to the first entry in remaining_waypoints.
-  // If back_to_back or shared trips are enabled, the waypoints may belong to a
-  // different trip.
+  // Note that the first waypoint may belong to a different trip.
   repeated google.type.LatLng route = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. An encoded path to the next waypoint. This field facilitates journey
-  // sharing between a driver app and a rider app. Note: This field is intended
-  // only for use by the Driver SDK and Consumer SDK.
+  // Output only. An encoded path to the next waypoint.
+  //
+  // Note: This field is intended only for use by the Driver SDK and Consumer
+  // SDK. Decoding is not yet supported.
   string current_route_segment = 21 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. Indicates the last time the route was modified.  Note: This field is
-  // intended only for use by the Driver SDK and Consumer SDK.
+  // Output only. Indicates the last time the route was modified.
+  //
+  // Note: This field is intended only for use by the Driver SDK and Consumer
+  // SDK.
   google.protobuf.Timestamp current_route_segment_version = 17 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Indicates the traffic conditions along the `current_route_segment` when
-  // they're available. Note: This field is intended only for use by the Driver
-  // SDK and Consumer SDK.
+  // they're available.
+  //
+  // Note: This field is intended only for use by the Driver SDK and Consumer
+  // SDK.
   ConsumableTrafficPolyline current_route_segment_traffic = 28 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Indicates the last time the `current_route_segment_traffic` was modified.
+  //
   // Note: This field is intended only for use by the Driver SDK and Consumer
   // SDK.
   google.protobuf.Timestamp current_route_segment_traffic_version = 30 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The waypoint where `current_route_segment` ends.
   TripWaypoint current_route_segment_end_point = 24 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The remaining driving distance in `current_route_segment` field. This
-  // field facilitates journey sharing between a driver and rider. The value
-  // is unspecified if the trip is not assigned to a vehicle or the trip is
-  // completed or cancelled.
+  // Output only. The remaining driving distance in the `current_route_segment` field. The
+  // value is unspecified if the trip is not assigned to a vehicle, or the trip
+  // is completed or cancelled.
   google.protobuf.Int32Value remaining_distance_meters = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The ETA to the next waypoint (the first entry in the
-  // `remaining_waypoints` field). This field facilitates journey sharing
-  // between a driver and a consumer. The value is unspecified if the trip is
-  // not assigned to a vehicle, or the trip is inactive (completed or
-  // cancelled).
+  // Output only. The ETA to the next waypoint (the first entry in the `remaining_waypoints`
+  // field). The value is unspecified if the trip is not assigned to a vehicle,
+  // or the trip is inactive (completed or cancelled).
   google.protobuf.Timestamp eta_to_first_waypoint = 13 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The duration from when the Trip data is returned to the time in
-  // `Trip.eta_to_first_waypoint`.
+  // `Trip.eta_to_first_waypoint`. The value is unspecified if the trip is not
+  // assigned to a vehicle, or the trip is inactive (completed or cancelled).
   google.protobuf.Duration remaining_time_to_first_waypoint = 27 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. Indicates the last time that `remaining_waypoints` was changed (a

diff --git a/google/maps/fleetengine/v1/vehicles.proto b/google/maps/fleetengine/v1/vehicles.proto
@@ -96,7 +96,9 @@ message Vehicle {
   // The polyline specifying the route the driver app intends to take to
   // the next waypoint. This list is also returned in
   // `Trip.current_route_segment` for all active trips assigned to the vehicle.
-  // Note: This field is intended only for use by the Driver SDK.
+  //
+  // Note: This field is intended only for use by the Driver SDK. Decoding is
+  // not yet supported.
   string current_route_segment = 20;
 
   // Input only. Fleet Engine uses this information to improve Journey Sharing.
@@ -115,31 +117,28 @@ message Vehicle {
   // `current_route_segment` is also specified.
   TripWaypoint current_route_segment_end_point = 24;
 
-  // The remaining driving distance for the `current_route_segment`. This field
-  // facilitates journey sharing between the Driver app and the Consumer app.
-  // This value is provided by the Driver SDK. This field is also returned in
-  // `Trip.remaining_distance_meters` for all active trips assigned to the
-  // vehicle. The value is unspecified if the `current_route_segment` field is
-  // empty, or if the Driver SDK has not updated its value.
+  // The remaining driving distance for the `current_route_segment`.
+  // This value is also returned in `Trip.remaining_distance_meters` for all
+  // active trips assigned to the vehicle. The value is unspecified if the
+  // `current_route_segment` field is empty.
   google.protobuf.Int32Value remaining_distance_meters = 18;
 
-  // The ETA to the first entry in the `waypoints` field. This field facilitates
-  // journey sharing between a driver app and a consumer app.  The Driver SDK
-  // provides the value under typical conditions. This field is also returned in
-  // `Trip.eta_to_first_waypoint` for all applicable trips assigned to the
-  // vehicle. The value is unspecified if the `waypoints` field is empty.
+  // The ETA to the first entry in the `waypoints` field.  The value is
+  // unspecified if the `waypoints` field is empty or the
+  // `Vehicle.current_route_segment` field is empty.
+  //
+  // When updating a vehicle, `remaining_time_seconds` takes precedence over
+  // `eta_to_first_waypoint` in the same request.
   google.protobuf.Timestamp eta_to_first_waypoint = 19;
 
-  // Input only. The remaining driving time for the `current_route_segment`. This field
-  // facilitates journey sharing between the Driver app and the Consumer app.
-  // This value is updated by the Driver SDK. The value is unspecified if the
+  // Input only. The remaining driving time for the `current_route_segment`. The value is
+  // unspecified if the `waypoints` field is empty or the
   // `Vehicle.current_route_segment` field is empty. This value should match
   // `eta_to_first_waypoint` - `current_time` if all parties are using the same
   // clock.
   //
-  // <p>When updating a vehicle, if you update both `eta_to_first_waypoint` and
-  // `remaining_time_seconds` in the same request, `remaining_time_seconds`
-  // takes precedence.
+  // When updating a vehicle, `remaining_time_seconds` takes precedence over
+  // `eta_to_first_waypoint` in the same request.
   google.protobuf.Int32Value remaining_time_seconds = 25 [(google.api.field_behavior) = INPUT_ONLY];
 
   // The remaining waypoints assigned to this Vehicle.