Merge pull request #12 from mapbox/direction-doc

Added some documentation to the rest of directions doc

libjava/lib/src/main/java/com/mapbox/services/directions/v4/DirectionsCriteria.java

@@ -1,20 +1,52 @@
 package com.mapbox.services.directions.v4;
 
 /**
- * Created by antonio on 1/30/16.
+ * Constants used to customize the directions request.
  */
 @Deprecated
 public final class DirectionsCriteria {
 
+    /**
+     * For car and motorcycle routing. This profile shows the fastest routes by preferring
+     * high-speed roads like highways.
+     */
     public static final String PROFILE_DRIVING = "mapbox.driving";
+
+    /**
+     * For pedestrian and hiking routing. This profile shows the shortest path by using sidewalks
+     * and trails.
+     */
     public static final String PROFILE_WALKING = "mapbox.walking";
+
+    /**
+     * For bicycle routing. This profile shows routes that are short and safe for cyclist, avoiding
+     * highways and preferring streets with bike lanes.
+     */
     public static final String PROFILE_CYCLING = "mapbox.cycling";
 
+    /**
+     * Format to return route instructions will be text.
+     */
     public static final String INSTRUCTIONS_TEXT = "text";
+
+    /**
+     * Format to return route instructions will be html.
+     */
     public static final String INSTRUCTIONS_HTML = "html";
 
-    public static final String GEOMETRY_GEOJSON  = "geojson";
+    /**
+     * Format to return route geometry will be geojson.
+     */
+    public static final String GEOMETRY_GEOJSON = "geojson";
+
+    /**
+     * Format to return route geometry will be encoded polyline.
+     */
     public static final String GEOMETRY_POLYLINE = "polyline";
-    public static final String GEOMETRY_FALSE    = "false";
+
+    /**
+     * Use false to omit geometry from response.
+     */
+    public static final String GEOMETRY_FALSE = "false";
 
 }

libjava/lib/src/main/java/com/mapbox/services/directions/v4/DirectionsService.java

@@ -9,11 +9,23 @@
 import rx.Observable;
 
 /**
- * Created by antonio on 1/30/16.
+ * Interface that defines the directions service (v4).
  */
 @Deprecated
 public interface DirectionsService {
 
+    /**
+     * Call-based interface
+     *
+     * @param profile
+     * @param waypoints
+     * @param accessToken
+     * @param alternatives
+     * @param instructions
+     * @param geometry
+     * @param steps
+     * @return A retrofit Call object
+     */
     @GET("v4/directions/{profile}/{waypoints}.json")
     Call<DirectionsResponse> getCall(
             @Path("profile") String profile,
@@ -25,6 +37,18 @@ Call<DirectionsResponse> getCall(
             @Query("steps") Boolean steps
     );
 
+    /**
+     * RxJava-based interface
+     *
+     * @param profile
+     * @param waypoints
+     * @param accessToken
+     * @param alternatives
+     * @param instructions
+     * @param geometry
+     * @param steps
+     * @return A RxJava Observable object
+     */
     @GET("v4/directions/{profile}/{waypoints}.json")
     Observable<DirectionsResponse> getObservable(
             @Path("profile") String profile,

libjava/lib/src/main/java/com/mapbox/services/directions/v4/MapboxDirections.java

@@ -24,7 +24,7 @@
 import rx.Observable;
 
 /**
- * Directions v4 are now deprecated in favor of v5
+ * @deprecated Directions v4 are now deprecated in favor of v5.
  */
 @Deprecated
 public class MapboxDirections implements MapboxService<DirectionsResponse> {
@@ -128,68 +128,122 @@ public static class Builder extends MapboxBuilder {
         private String geometry;
         private Boolean steps;
 
+        /**
+         * Required to call when building {@link com.mapbox.services.directions.v4.MapboxDirections.Builder}.
+         *
+         * @param accessToken Mapbox access token, You must have a Mapbox account inorder to use
+         *                    this library.
+         */
         @Override
         public Builder setAccessToken(String accessToken) {
             this.accessToken = accessToken;
             return this;
         }
 
+        /**
+         * Specify what routing profile you'd like: driving, walking, or cycling.
+         *
+         * @param profile {@link DirectionsCriteria#PROFILE_DRIVING},
+         * {@link DirectionsCriteria#PROFILE_CYCLING}, or {@link DirectionsCriteria#PROFILE_WALKING}
+         */
         public Builder setProfile(String profile) {
             this.profile = profile;
             return this;
         }
 
-        /*
-         * We offer some convenience for the typical case where we only have an origin
-         * and a destination. Instead of having to create a List of waypoints, we just
-         * call setOrigin() and setDestination() which is more meaningful. That's taken
-         * into account in getWaypoints()
+        /**
+         * If you have more then one destination, call this method passing in a list of all
+         * waypoints including origin and final destination.
+         *
+         * @param waypoints List including all {@link Waypoint} you'd line to include in route.
          */
-
         public Builder setWaypoints(List<Waypoint> waypoints) {
             this.waypoints = waypoints;
             return this;
         }
 
+        /**
+         * Origin of the destination.
+         *
+         * @param origin {@link Waypoint} of origin.
+         */
         public Builder setOrigin(Waypoint origin) {
             this.origin = origin;
             return this;
         }
 
+        /**
+         * Final destination of your route, call this only if you have one destination, otherwise,
+         * use {@link #setWaypoints(List)}
+         *
+         * @param destination {@link Waypoint} of destination.
+         */
         public Builder setDestination(Waypoint destination) {
             this.destination = destination;
             return this;
         }
 
+        /**
+         * Optionally, call if you'd like to receive alternative routes besides just one.
+         *
+         * @param alternatives true if you'd like alternative routes, else false.
+         */
         public Builder setAlternatives(Boolean alternatives) {
             this.alternatives = alternatives;
             return this;
         }
 
+        /**
+         * Optionally, call if you'd like to receive human-readable instructions.
+         *
+         * @param instructions {@link DirectionsCriteria#INSTRUCTIONS_TEXT} or
+         * {@link DirectionsCriteria#INSTRUCTIONS_HTML}
+         */
         public Builder setInstructions(String instructions) {
             this.instructions = instructions;
             return this;
         }
 
+        /**
+         * Optionally, call with the format you'd like the route geometry to be in.
+         *
+         * @param geometry {@link DirectionsCriteria#GEOMETRY_GEOJSON},
+         * {@link DirectionsCriteria#GEOMETRY_POLYLINE}, or {@link DirectionsCriteria#GEOMETRY_FALSE}
+         */
         public Builder setGeometry(String geometry) {
             this.geometry = geometry;
             return this;
         }
 
+        /**
+         * Optionally, call if you'd like to include step information within route.
+         *
+         * @param steps true if you'd like step information.
+         */
         public Builder setSteps(Boolean steps) {
             this.steps = steps;
             return this;
         }
 
+        /**
+         * @return your Mapbox access token.
+         */
         @Override
         public String getAccessToken() {
             return accessToken;
         }
 
+        /**
+         * @return {@link DirectionsCriteria#PROFILE_DRIVING},
+         * {@link DirectionsCriteria#PROFILE_CYCLING}, or {@link DirectionsCriteria#PROFILE_WALKING}
+         */
         public String getProfile() {
             return profile;
         }
 
+        /**
+         * @return List including all {@link Waypoint} within route.
+         */
         public String getWaypoints() {
             String waypointsFormatted = "";
 
@@ -214,26 +268,46 @@ public String getWaypoints() {
             return waypointsFormatted;
         }
 
+        /**
+         * @return routes origin {@link Waypoint}.
+         */
         public Waypoint getOrigin() {
             return origin;
         }
 
+        /**
+         * @return routes final destination {@link Waypoint}.
+         */
         public Waypoint getDestination() {
             return destination;
         }
 
+        /**
+         * @return true if you {@link #setAlternatives(Boolean)} to true.
+         */
         public Boolean isAlternatives() {
             return alternatives;
         }
 
+        /**
+         * @return {@link DirectionsCriteria#INSTRUCTIONS_TEXT} or
+         * {@link DirectionsCriteria#INSTRUCTIONS_HTML}
+         */
         public String getInstructions() {
             return instructions;
         }
 
+        /**
+         * @return {@link DirectionsCriteria#GEOMETRY_GEOJSON},
+         * {@link DirectionsCriteria#GEOMETRY_POLYLINE}, or {@link DirectionsCriteria#GEOMETRY_FALSE}
+         */
         public String getGeometry() {
             return geometry;
         }
 
+        /**
+         * @return true if you requested step information in {@link #setSteps(Boolean)}.
+         */
         public Boolean isSteps() {
             return steps;
         }

libjava/lib/src/main/java/com/mapbox/services/directions/v5/DirectionsCriteria.java

@@ -1,43 +1,73 @@
 package com.mapbox.services.directions.v5;
 
 /**
- * Created by antonio on 3/4/16.
+ * Constants used to customize the directions request.
  */
 public class DirectionsCriteria {
 
+    public static final String PROFILE_DEFAULT_USER = "mapbox";
+
     /**
-     The profile parameter denotes the type of routing. Currently supported are:
-     - mapbox/driving for car routing
-     - mapbox/walking for pedestrian and hiking routing
-     - mapbox/cycling for bicycle routing
+     * For car and motorcycle routing. This profile shows the fastest routes by preferring
+     * high-speed roads like highways.
      */
-    public static final String PROFILE_DEFAULT_USER = "mapbox";
     public static final String PROFILE_DRIVING = "driving";
+
+    /**
+     * For pedestrian and hiking routing. This profile shows the shortest path by using sidewalks
+     * and trails.
+     */
     public static final String PROFILE_WALKING = "walking";
+
+    /**
+     * For bicycle routing. This profile shows routes that are short and safe for cyclist, avoiding
+     * highways and preferring streets with bike lanes.
+     */
     public static final String PROFILE_CYCLING = "cycling";
 
     /**
-     * Format in which geometries are returned
+     * Format to return route geometry will be encoded polyline.
      */
     public final static String GEOMETRY_POLYLINE = "polyline";
-    private final static String GEOMETRY_GEOJSON = "geojson"; // Unsupported
 
     /**
-     * Add overview geometry either full, simplified to the highest zoom level it could be
-     * display on, or not at all
+     * Format to return route geometry will be geojson. Note that this isn't supported by the SDK.
+     */
+    private final static String GEOMETRY_GEOJSON = "geojson";
+
+    /**
+     * A simplified version of the {@link #OVERVIEW_FULL} geometry. If not specified simplified is the default.
      */
     public final static String OVERVIEW_SIMPLIFIED = "simplified";
+
+    /**
+     * The most detailed geometry available.
+     */
     public final static String OVERVIEW_FULL = "full";
+
+    /**
+     * No overview geometry.
+     */
     public final static String OVERVIEW_FALSE = "false";
 
     /**
-     * On error, the server responds with an HTTP status code denoting the error, as explained in
-     * the table below. The response body may include a JSON object with a message property,
-     * explaining the error.
+     * Server responds with no errors.
      */
     public final static String RESPONSE_OK = "Ok";
+
+    /**
+     * There was no route found for the given query.
+     */
     public final static String RESPONSE_NO_ROUTE = "NoRoute";
+
+    /**
+     * Use a valid profile as described above.
+     */
     public final static String RESPONSE_PROFILE_NOT_FOUND = "ProfileNotFound";
+
+    /**
+     * The given request was not valid.
+     */
     public final static String RESPONSE_INVALID_INPUT = "InvalidInput";
 
 }