Add missing documentation to TransitRequest, VehicleParkingRequest an…

…d VehicleRentalRequest
opentripplanner · Sep 12, 2022 · 01b7dd1 · 01b7dd1
1 parent 201aa60
commit 01b7dd1
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 0 deletions.
diff --git a/src/main/java/org/opentripplanner/routing/api/request/request/TransitRequest.java b/src/main/java/org/opentripplanner/routing/api/request/request/TransitRequest.java
@@ -15,11 +15,20 @@ public class TransitRequest implements Cloneable, Serializable {
 
   private List<FeedScopedId> whiteListedAgencies = List.of();
   private List<FeedScopedId> bannedAgencies = List.of();
+
+  @Deprecated
   private List<FeedScopedId> preferredAgencies = List.of();
+
   private List<FeedScopedId> unpreferredAgencies = List.of();
   private RouteMatcher whiteListedRoutes = RouteMatcher.emptyMatcher();
   private RouteMatcher bannedRoutes = RouteMatcher.emptyMatcher();
+
+  /**
+   * @deprecated TODO OTP2 Needs to be implemented
+   */
+  @Deprecated
   private List<FeedScopedId> preferredRoutes = List.of();
+
   private List<FeedScopedId> unpreferredRoutes = List.of();
   private List<FeedScopedId> bannedTrips = List.of();
   private DebugRaptor raptorDebugging = new DebugRaptor();
@@ -38,6 +47,9 @@ public void setWhiteListedAgenciesFromSting(String s) {
     }
   }
 
+  /**
+   * Only use certain named agencies
+   */
   public void setWhiteListedAgencies(List<FeedScopedId> whiteListedAgencies) {
     this.whiteListedAgencies = whiteListedAgencies;
   }
@@ -46,12 +58,18 @@ public List<FeedScopedId> whiteListedAgencies() {
     return whiteListedAgencies;
   }
 
+  /**
+   * Do not use certain named agencies
+   */
   public void setBannedAgenciesFromSting(String s) {
     if (!s.isEmpty()) {
       bannedAgencies = FeedScopedId.parseListOfIds(s);
     }
   }
 
+  /**
+   * Do not use certain named agencies
+   */
   public void setBannedAgencies(List<FeedScopedId> bannedAgencies) {
     this.bannedAgencies = bannedAgencies;
   }
@@ -60,16 +78,22 @@ public List<FeedScopedId> bannedAgencies() {
     return bannedAgencies;
   }
 
+  @Deprecated
   public void setPreferredAgenciesFromString(String s) {
     if (!s.isEmpty()) {
       preferredAgencies = FeedScopedId.parseListOfIds(s);
     }
   }
 
+  @Deprecated
   public void setPreferredAgencies(List<FeedScopedId> preferredAgencies) {
     this.preferredAgencies = preferredAgencies;
   }
 
+  /**
+   * List of preferred agencies by user.
+   */
+  @Deprecated
   public List<FeedScopedId> preferredAgencies() {
     return preferredAgencies;
   }
@@ -80,6 +104,9 @@ public void setUnpreferredAgenciesFromString(String s) {
     }
   }
 
+  /**
+   * List of unpreferred agencies for given user.
+   */
   public void setUnpreferredAgencies(List<FeedScopedId> unpreferredAgencies) {
     this.unpreferredAgencies = unpreferredAgencies;
   }
@@ -88,6 +115,9 @@ public List<FeedScopedId> unpreferredAgencies() {
     return unpreferredAgencies;
   }
 
+  /**
+   * Only use certain named routes
+   */
   public void setWhiteListedRoutesFromString(String s) {
     if (!s.isEmpty()) {
       whiteListedRoutes = RouteMatcher.parse(s);
@@ -96,14 +126,25 @@ public void setWhiteListedRoutesFromString(String s) {
     }
   }
 
+  /**
+   * Only use certain named routes
+   */
   public void setWhiteListedRoutes(RouteMatcher whiteListedRoutes) {
     this.whiteListedRoutes = whiteListedRoutes;
   }
 
+  /**
+   * Only use certain named routes
+   */
   public RouteMatcher whiteListedRoutes() {
     return whiteListedRoutes;
   }
 
+  /**
+   * Do not use certain named routes. The paramter format is: feedId_routeId,feedId_routeId,feedId_routeId
+   * This parameter format is completely nonstandard and should be revised for the 2.0 API, see
+   * issue #1671.
+   */
   public void setBannedRoutesFromString(String s) {
     if (!s.isEmpty()) {
       bannedRoutes = RouteMatcher.parse(s);
@@ -112,6 +153,11 @@ public void setBannedRoutesFromString(String s) {
     }
   }
 
+  /**
+   * Do not use certain named routes. The paramter format is: feedId_routeId,feedId_routeId,feedId_routeId
+   * This parameter format is completely nonstandard and should be revised for the 2.0 API, see
+   * issue #1671.
+   */
   public void setBannedRoutes(RouteMatcher bannedRoutes) {
     this.bannedRoutes = bannedRoutes;
   }
@@ -120,6 +166,7 @@ public RouteMatcher bannedRoutes() {
     return bannedRoutes;
   }
 
+  @Deprecated
   public void setPreferredRoutesFromString(String s) {
     if (!s.isEmpty()) {
       preferredRoutes = List.copyOf(FeedScopedId.parseListOfIds(s));
@@ -128,10 +175,15 @@ public void setPreferredRoutesFromString(String s) {
     }
   }
 
+  @Deprecated
   public void setPreferredRoutes(List<FeedScopedId> preferredRoutes) {
     this.preferredRoutes = preferredRoutes;
   }
 
+  /**
+   * Set of preferred routes by user and configuration.
+   */
+  @Deprecated
   public List<FeedScopedId> preferredRoutes() {
     return preferredRoutes;
   }
@@ -148,16 +200,25 @@ public void setUnpreferredRoutes(List<FeedScopedId> unpreferredRoutes) {
     this.unpreferredRoutes = unpreferredRoutes;
   }
 
+  /**
+   * Set of unpreferred routes for given user and configuration.
+   */
   public List<FeedScopedId> unpreferredRoutes() {
     return unpreferredRoutes;
   }
 
+  /**
+   * Do not use certain trips
+   */
   public void setBannedTripsFromString(String ids) {
     if (!ids.isEmpty()) {
       bannedTrips = FeedScopedId.parseListOfIds(ids);
     }
   }
 
+  /**
+   * Do not use certain trips
+   */
   public void setBannedTrips(List<FeedScopedId> bannedTrips) {
     this.bannedTrips = bannedTrips;
   }

diff --git a/src/main/java/org/opentripplanner/routing/api/request/request/VehicleParkingRequest.java b/src/main/java/org/opentripplanner/routing/api/request/request/VehicleParkingRequest.java
@@ -16,6 +16,7 @@ public void setRequiredTags(Set<String> requiredTags) {
     this.requiredTags = requiredTags;
   }
 
+  /** Tags which are required to use a vehicle parking. If empty, no tags are required. */
   public Set<String> requiredTags() {
     return requiredTags;
   }
@@ -24,6 +25,7 @@ public void setBannedTags(Set<String> bannedTags) {
     this.bannedTags = bannedTags;
   }
 
+  /** Tags with which a vehicle parking will not be used. If empty, no tags are banned. */
   public Set<String> bannedTags() {
     return bannedTags;
   }

diff --git a/src/main/java/org/opentripplanner/routing/api/request/request/VehicleRentalRequest.java b/src/main/java/org/opentripplanner/routing/api/request/request/VehicleRentalRequest.java
@@ -20,6 +20,7 @@ public void setAllowedNetworks(Set<String> allowedNetworks) {
     this.allowedNetworks = allowedNetworks;
   }
 
+  /** The vehicle rental networks which may be used. If empty all networks may be used. */
   public Set<String> allowedNetworks() {
     return allowedNetworks;
   }
@@ -28,6 +29,7 @@ public void setBannedNetworks(Set<String> bannedNetworks) {
     this.bannedNetworks = bannedNetworks;
   }
 
+  /** The vehicle rental networks which may not be used. If empty, no networks are banned. */
   public Set<String> bannedNetworks() {
     return bannedNetworks;
   }