improved documentation

rinde · May 4, 2017 · 75ca662 · 75ca662
1 parent eab73e8
commit 75ca662
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 47 deletions.
diff --git a/core/src/main/java/com/github/rinde/rinsim/core/model/road/MoveProgress.java b/core/src/main/java/com/github/rinde/rinsim/core/model/road/MoveProgress.java
@@ -32,9 +32,8 @@
 import com.google.common.collect.ImmutableList;
 
 /**
- * Represents the distance traveled and time spent in
- * {@link RoadModel#followPath(MovingRoadUser, java.util.Queue, com.github.rinde.rinsim.core.model.time.TimeLapse)}
- * .
+ * Value object representing the distance traveled and time spent of a
+ * {@link MovingRoadUser}.
  * @author Bartosz Michalik
  * @author Rinde van Lon
  * @since 2.0

diff --git a/core/src/main/java/com/github/rinde/rinsim/core/model/road/RoadModel.java b/core/src/main/java/com/github/rinde/rinsim/core/model/road/RoadModel.java
@@ -34,6 +34,7 @@
 import com.github.rinde.rinsim.core.model.time.TimeLapse;
 import com.github.rinde.rinsim.event.EventAPI;
 import com.github.rinde.rinsim.geom.GeomHeuristic;
+import com.github.rinde.rinsim.geom.GeomHeuristics;
 import com.github.rinde.rinsim.geom.Point;
 import com.google.common.base.Predicate;
 import com.google.common.collect.ImmutableList;
@@ -47,20 +48,22 @@
  * <li>adding and removing objects</li>
  * <li>moving objects around</li>
  * </ul>
- * On top of that the RoadModel provides several functions for retrieving
- * objects and finding the shortest path. More utilities for working with
+ * Additionally, the RoadModel provides several methods for retrieving objects
+ * and finding the shortest path. More utilities for working with
  * {@link RoadModel}s are defined in {@link RoadModels}.
  * @author Rinde van Lon
  */
 public interface RoadModel extends Model<RoadUser> {
 
   /**
    * Moves the specified {@link MovingRoadUser} towards the specified
-   * <code>destination</code> using the path returned by
-   * {@link #getShortestPathTo(RoadUser, Point)}. There must be time left in the
-   * provided {@link TimeLapse}. The {@link #getDestination(MovingRoadUser)}
-   * method will return the destination point as specified in the most recent
-   * invocation of this method.
+   * <code>destination</code> following the path returned by
+   * {@link #getPathTo(MovingRoadUser, Point, Unit, Measure, GeomHeuristic)}.
+   * The {@link GeomHeuristic} that is used by default is
+   * {@link GeomHeuristics#euclidean()}. There must be time left in the provided
+   * {@link TimeLapse}. The {@link #getDestination(MovingRoadUser)} method will
+   * return the destination point as specified in the most recent invocation of
+   * this method.
    * <p>
    * <b>Speed</b><br>
    * The {@link MovingRoadUser} has to define a speed with which it wants to
@@ -91,11 +94,12 @@ public interface RoadModel extends Model<RoadUser> {
 
   /**
    * Moves the specified {@link MovingRoadUser} towards the specified
-   * <code>destination</code> using the path returned by
-   * {@link #getShortestPathTo(RoadUser, RoadUser)}. There must be time left in
-   * the provided {@link TimeLapse}. The {@link #getDestination(MovingRoadUser)}
-   * method will return the destination point as specified in the most recent
-   * invocation of this method.
+   * <code>destination</code> following the path returned by
+   * {@link #getPathTo(MovingRoadUser, Point, Unit, Measure, GeomHeuristic)}.
+   * The {@link GeomHeuristic} that is used by default is
+   * {@link GeomHeuristics#euclidean()}. The
+   * {@link #getDestination(MovingRoadUser)} method will return the destination
+   * point as specified in the most recent invocation of this method.
    * <p>
    * <b>Speed</b><br>
    * The {@link MovingRoadUser} has to define a speed with which it wants to
@@ -127,11 +131,13 @@ MoveProgress moveTo(MovingRoadUser object, RoadUser destination,
 
   /**
    * Moves the specified {@link MovingRoadUser} towards the specified
-   * <code>destination</code> using the path returned by
-   * {@link #getPathTo(Point, Point, Unit, Measure, GeomHeuristic)}. There must
-   * be time left in the provided {@link TimeLapse}. The
-   * {@link #getDestination(MovingRoadUser)} method will return the destination
-   * point as specified in the most recent invocation of this method.
+   * <code>destination</code> following the path returned by
+   * {@link #getPathTo(MovingRoadUser, Point, Unit, Measure, GeomHeuristic)}.
+   * The {@link GeomHeuristic} that is used can be specified via
+   * <code>heuristic</code>. There must be time left in the provided
+   * {@link TimeLapse}. The {@link #getDestination(MovingRoadUser)} method will
+   * return the destination point as specified in the most recent invocation of
+   * this method.
    * <p>
    * <b>Speed</b><br>
    * The {@link MovingRoadUser} has to define a speed with which it wants to
@@ -154,22 +160,23 @@ MoveProgress moveTo(MovingRoadUser object, RoadUser destination,
    * @param time The time that is available for travel.
    * @param heuristic The heuristic to use for path resolution.
    * @return A {@link MoveProgress} instance which details: the distance
-   *         travelled, the actual time spent travelling and the nodes which
-   *         where travelled.
+   *         traveled, the actual time spent traveling and the nodes which where
+   *         traveled.
    * @see #moveTo(MovingRoadUser, Point, TimeLapse)
    * @see #followPath(MovingRoadUser, Queue, TimeLapse)
    */
   MoveProgress moveTo(MovingRoadUser object, RoadUser destination,
-      TimeLapse time,
-      GeomHeuristic heuristic);
+      TimeLapse time, GeomHeuristic heuristic);
 
   /**
    * Moves the specified {@link MovingRoadUser} towards the specified
-   * <code>destination</code> using the path returned by
-   * {@link #getPathTo(Point, Point, Unit, Measure, GeomHeuristic)}. There must
-   * be time left in the provided {@link TimeLapse}. The
-   * {@link #getDestination(MovingRoadUser)} method will return the destination
-   * point as specified in the most recent invocation of this method.
+   * <code>destination</code> following the path returned by
+   * {@link #getPathTo(MovingRoadUser, Point, Unit, Measure, GeomHeuristic)}.
+   * The {@link GeomHeuristic} that is used can be specified via
+   * <code>heuristic</code>. There must be time left in the provided
+   * {@link TimeLapse}. The {@link #getDestination(MovingRoadUser)} method will
+   * return the destination point as specified in the most recent invocation of
+   * this method.
    * <p>
    * <b>Speed</b><br>
    * The {@link MovingRoadUser} has to define a speed with which it wants to
@@ -192,17 +199,16 @@ MoveProgress moveTo(MovingRoadUser object, RoadUser destination,
    * @param time The time that is available for travel.
    * @param heuristic The heuristic to use for path resolution.
    * @return A {@link MoveProgress} instance which details: the distance
-   *         travelled, the actual time spent travelling and the nodes which
-   *         where travelled.
+   *         traveled, the actual time spent traveling and the nodes which where
+   *         traveled.
    * @see #moveTo(MovingRoadUser, RoadUser, TimeLapse)
    * @see #followPath(MovingRoadUser, Queue, TimeLapse)
    */
-  MoveProgress moveTo(MovingRoadUser object, Point destination,
-      TimeLapse time,
+  MoveProgress moveTo(MovingRoadUser object, Point destination, TimeLapse time,
       GeomHeuristic heuristic);
 
   /**
-   * Moves the specified {@link MovingRoadUser} using the specified path and
+   * Moves the specified {@link MovingRoadUser} following the specified path and
    * with the specified time. The provided <code>path</code> can not be empty
    * and there must be time left in the provided {@link TimeLapse}.
    * <p>
@@ -281,7 +287,7 @@ MoveProgress followPath(MovingRoadUser object, Queue<Point> path,
   void removeObject(RoadUser roadUser);
 
   /**
-   * Removes all objects on this RoadStructure instance.
+   * Removes all objects from this road model.
    */
   void clear();
 
@@ -419,7 +425,7 @@ MoveProgress followPath(MovingRoadUser object, Queue<Point> path,
   List<Point> getShortestPathTo(RoadUser fromObj, Point to);
 
   /**
-   * Finds the shortest between <code>from</code> and <code>to</code>. The
+   * Finds the shortest path between <code>from</code> and <code>to</code>. The
    * definition of a <i>shortest</i> path is defined by the specific
    * implementation, possibilities include the shortest travel time and the
    * shortest distance.
@@ -430,8 +436,10 @@ MoveProgress followPath(MovingRoadUser object, Queue<Point> path,
   List<Point> getShortestPathTo(Point from, Point to);
 
   /**
-   * Finds a path that is optimal according to the given {@link GeomHeuristic}
-   * between the points <code>from</code> and <code>to</code>.
+   * Finds a path between <code>from</code> and <code>to</code>. The path
+   * finding is directed by the specified {@link GeomHeuristic}, this heuristic
+   * determines the property of the path that is minimized (e.g. travel time,
+   * distance traveled, etc.).
    * @param from The starting point.
    * @param to The ending point.
    * @param timeUnit The time unit to use for the calculations.
@@ -445,9 +453,10 @@ RoadPath getPathTo(Point from, Point to, Unit<Duration> timeUnit,
       Measure<Double, Velocity> maxSpeed, GeomHeuristic heuristic);
 
   /**
-   * Finds a path that is optimal according to the given {@link GeomHeuristic}
-   * between current position of the <code>object</code> and its destination at
-   * point <code>destination</code>.
+   * Finds a path between <code>object</code> and <code>destination</code>. The
+   * path finding is directed by the specified {@link GeomHeuristic}, this
+   * heuristic determines the property of the path that is minimized (e.g.
+   * travel time, distance traveled, etc.).
    * @param object The road user.
    * @param destination The ending point.
    * @param timeUnit The time unit to use for the calculations.

diff --git a/core/src/main/java/com/github/rinde/rinsim/core/model/road/RoadPath.java b/core/src/main/java/com/github/rinde/rinsim/core/model/road/RoadPath.java
@@ -22,9 +22,9 @@
 import com.google.auto.value.AutoValue;
 
 /**
- * An immutable class containing a path with a certain heuristic value and
- * travel time. The heuristic value is the result of determining the value of
- * the path by a {@link GeomHeuristic}.
+ * A value object containing a path with a certain heuristic value and travel
+ * time. The heuristic value is the result of determining the value of the path
+ * by a {@link GeomHeuristic}.
  * @author Vincent Van Gestel
  */
 @AutoValue

diff --git a/pdptw/src/main/java/com/github/rinde/rinsim/pdptw/common/RouteFollowingVehicle.java b/pdptw/src/main/java/com/github/rinde/rinsim/pdptw/common/RouteFollowingVehicle.java
@@ -142,7 +142,9 @@ public RouteFollowingVehicle(VehicleDTO dto,
    *          {@link #setRoute(Iterable)} method.
    * @param adjuster Allows to set a route adjuster to 'fix' routes if
    *          necessary.
-   * @param heuristic The {@link GeomHeuristic} to decide optimal routes.
+   * @param heuristic The {@link GeomHeuristic} is used for path finding, it
+   *          determines the property of the path that is minimized (e.g. travel
+   *          time, distance traveled, etc.).
    */
   public RouteFollowingVehicle(VehicleDTO dto,
       boolean allowDelayedRouteChanging, RouteAdjuster adjuster,
@@ -418,8 +420,8 @@ protected boolean isTooEarly(Parcel p, TimeLapse time) {
    */
   protected long computeTravelTimeTo(Point p, Unit<Duration> timeUnit) {
     return DoubleMath.roundToLong(
-      getRoadModel().getPathTo(this, p, timeUnit,
-        speed.get(), routeHeuristic).getTravelTime(),
+      getRoadModel().getPathTo(this, p, timeUnit, speed.get(), routeHeuristic)
+        .getTravelTime(),
       RoundingMode.CEILING);
   }