Missing javadoc added (#442)

* added some javadoc fixes

* finished adding missing javadoc

* added optimized trip javadoc

* fixed checkstyle issue

Author: Cameron Mace

mapbox/libandroid-services/gradle-javadoc.gradle

@@ -5,7 +5,7 @@ android.libraryVariants.all { variant ->
         failOnError = false
         destinationDir = new File(destinationDir, variant.baseName)
         source = files(variant.javaCompile.source)
-        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath) + files("../../../../libjava/lib/src/main/java")
+        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath) + files("../libjava-services/lib/src/main/java")
         options.windowTitle("Mapbox Android Services SDK $VERSION_NAME Reference")
         options.docTitle("Mapbox Android Services SDK $VERSION_NAME")
         options.header("Mapbox Android Services SDK $VERSION_NAME Reference")

mapbox/libandroid-telemetry/gradle-javadoc.gradle

@@ -5,7 +5,7 @@ android.libraryVariants.all { variant ->
         failOnError = false
         destinationDir = new File(destinationDir, variant.baseName)
         source = files(variant.javaCompile.source)
-        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath) + files("../../../../libjava/lib/src/main/java")
+        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath)
         options.windowTitle("Mapbox Android Services SDK $VERSION_NAME Reference")
         options.docTitle("Mapbox Android Services SDK $VERSION_NAME")
         options.header("Mapbox Android Services SDK $VERSION_NAME Reference")

mapbox/libandroid-ui/gradle-javadoc.gradle

@@ -5,7 +5,7 @@ android.libraryVariants.all { variant ->
         failOnError = false
         destinationDir = new File(destinationDir, variant.baseName)
         source = files(variant.javaCompile.source)
-        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath)
+        classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath) + files("../libandroid-services/lib/src/main/java")
         options.windowTitle("Mapbox Android Services SDK $VERSION_NAME Reference")
         options.docTitle("Mapbox Android Services SDK $VERSION_NAME")
         options.header("Mapbox Android Services SDK $VERSION_NAME Reference")

mapbox/libjava-core/src/main/java/com/mapbox/services/commons/utils/TextUtils.java

@@ -71,6 +71,7 @@ public static String formatCoordinate(double coordinate) {
    * Allows the specific adjusting of a coordinates precision.
    *
    * @param coordinate a double value representing a coordinate.
+   * @param precision  an integer value you'd like the precision to be at.
    * @return a formatted string.
    * @since 2.1.0
    */

mapbox/libjava-services-rx/src/main/java/com/mapbox/services/api/rx/directionsmatrix/v1/DirectionsMatrixServiceRx.java

@@ -29,6 +29,7 @@ public interface DirectionsMatrixServiceRx {
    * @param sources      Array of waypoint objects. Each waypoints is an input coordinate snapped to the road and path
    *                     network. The waypoints appear in the array in the order of the input coordinates, or in the
    *                     order as specified in the sources query parameter.
+   * @return A retrofit Observable object
    * @since 2.1.0
    */
   @GET("directions-matrix/v1/{user}/{profile}/{coordinates}")

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/DirectionsService.java

@@ -35,6 +35,7 @@ public interface DirectionsService {
    * @param annotations      An annotations object that contains additional details about each line segment along the
    *                         route geometry. Each entry in an annotations field corresponds to a coordinate along the
    *                         route geometry.
+   * @return The {@link DirectionsResponse} in a Call wrapper.
    * @since 1.0.0
    */
   @GET("directions/v5/{user}/{profile}/{coordinates}")

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/MapboxDirections.java

@@ -349,8 +349,7 @@ public T setContinueStraight(Boolean continueStraight) {
      *
      * @param annotation String referencing one of the annotation direction criteria's.
      * @return Builder
-     * @see <a href="https://www.mapbox.com/api-documentation/#routeleg-object">RouteLeg object documentation</a> for
-     * more information.
+     * @see <a href="https://www.mapbox.com/api-documentation/#routeleg-object">RouteLeg object documentation</a>
      * @since 2.1.0
      */
     public T setAnnotation(String... annotation) {
@@ -371,6 +370,8 @@ public String getUser() {
     }
 
     /**
+     * The current profile set for usage with the Directions API.
+     *
      * @return {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#PROFILE_DRIVING_TRAFFIC},
      * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#PROFILE_DRIVING},
      * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#PROFILE_CYCLING},
@@ -540,11 +541,25 @@ public String getAnnotation() {
       return TextUtils.join(",", annotation);
     }
 
+    /**
+     * Base package name or other simple string identifier
+     *
+     * @param appName base package name or other simple string identifier
+     * @return Builder
+     * @since 1.3.0
+     */
     public T setClientAppName(String appName) {
       super.clientAppName = appName;
       return (T) this;
     }
 
+    /**
+     * Optionally change the APIs base URL to something other then the default Mapbox one.
+     *
+     * @param baseUrl base url used as end point
+     * @return Builder
+     * @since 1.3.0
+     */
     public T setBaseUrl(String baseUrl) {
       super.baseUrl = baseUrl;
       return (T) this;

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/models/DirectionsResponse.java

@@ -13,9 +13,22 @@ public class DirectionsResponse {
   private List<DirectionsRoute> routes;
   private List<DirectionsWaypoint> waypoints;
 
+  /**
+   * Empty constructor
+   *
+   * @since 2.1.0
+   */
   public DirectionsResponse() {
   }
 
+  /**
+   * Constructor taking in both a list of {@link DirectionsRoute} and a list of {@link DirectionsWaypoint}s.
+   *
+   * @param routes    list of routes you can pass in while building this object.
+   * @param waypoints list of waypoints you can pass in while building this object. Ideally these should match what was
+   *                  used to crate the route.
+   * @since 2.0.0
+   */
   public DirectionsResponse(List<DirectionsRoute> routes, List<DirectionsWaypoint> waypoints) {
     this.routes = routes;
     this.waypoints = waypoints;
@@ -32,6 +45,13 @@ public String getCode() {
     return code;
   }
 
+  /**
+   * String indicating the state of the response. This is a separate code than the HTTP
+   * status code.
+   *
+   * @param code "Ok", "NoRoute", "ProfileNotFound", or "InvalidInput".
+   * @since 2.1.0
+   */
   public void setCode(String code) {
     this.code = code;
   }
@@ -47,6 +67,13 @@ public List<DirectionsWaypoint> getWaypoints() {
     return waypoints;
   }
 
+  /**
+   * List with Waypoints of locations snapped to the road and path network and should appear in the List
+   * in the order of the input coordinates.
+   *
+   * @param waypoints List of {@link DirectionsWaypoint} objects.
+   * @since 2.1.0
+   */
   public void setWaypoints(List<DirectionsWaypoint> waypoints) {
     this.waypoints = waypoints;
   }
@@ -64,6 +91,15 @@ public List<DirectionsRoute> getRoutes() {
     return routes;
   }
 
+  /**
+   * List containing all the different route options. It should be ordered by descending recommendation
+   * rank. In other words, object 0 in the List is the highest recommended route. if you don't
+   * setAlternatives to true (default is false) in your builder this should always be a List of
+   * size 1.
+   *
+   * @param routes List of {@link DirectionsRoute} objects.
+   * @since 2.1.0
+   */
   public void setRoutes(List<DirectionsRoute> routes) {
     this.routes = routes;
   }

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/models/DirectionsRoute.java

@@ -34,27 +34,56 @@ public double getDistance() {
 
   /**
    * The distance traveled from origin to destination.
-   * <p>
-   * Sets a double number with unit meters.
    *
-   * @since 2.0.1
+   * @param distance a double number with unit meters.
+   * @since 2.1.0
    */
   public void setDistance(double distance) {
     this.distance = distance;
   }
 
+  /**
+   * The name of the weight profile used while calculating during extraction phase. In many cases, this will return
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_ROUTABILITY},
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_DURATION}, or
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_DISTANCE}.
+   *
+   * @return a String representing the weight profile used while calculating the route.
+   * @since 2.1.0
+   */
   public String getWeightName() {
     return weightName;
   }
 
+  /**
+   * The name of the weight profile used while calculating during extraction phase. In many cases, this would be
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_ROUTABILITY},
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_DURATION}, or
+   * {@link com.mapbox.services.api.directions.v5.DirectionsCriteria#WEIGHT_NAME_DISTANCE}.
+   *
+   * @param weightName a String representing the weight profile used while calculating the route.
+   * @since 2.1.0
+   */
   public void setWeightName(String weightName) {
     this.weightName = weightName;
   }
 
+  /**
+   * The calculated weight of the route.
+   *
+   * @return the weight value provided from the API as a {@code double} value.
+   * @since 2.1.0
+   */
   public double getWeight() {
     return weight;
   }
 
+  /**
+   * The calculated weight of the route.
+   *
+   * @param weight the weight value as a {@code double} value.
+   * @since 2.1.0
+   */
   public void setWeight(double weight) {
     this.weight = weight;
   }
@@ -71,10 +100,9 @@ public double getDuration() {
 
   /**
    * The estimated travel time from origin to destination.
-   * <p>
-   * Sets a double number with unit seconds.
    *
-   * @since 2.0.1
+   * @param duration a double number with unit seconds.
+   * @since 2.1.0
    */
   public void setDuration(double duration) {
     this.duration = duration;
@@ -92,16 +120,14 @@ public String getGeometry() {
 
   /**
    * Sets the geometry of the route. Commonly used to draw the route on the map view.
-   * <p>
-   * Sets An encoded polyline string.
    *
-   * @since 2.0.1
+   * @param geometry an encoded polyline string.
+   * @since 2.1.0
    */
   public void setGeometry(String geometry) {
     this.geometry = geometry;
   }
 
-
   /**
    * A Leg is a route between only two waypoints
    *
@@ -112,17 +138,13 @@ public List<RouteLeg> getLegs() {
     return legs;
   }
 
-
   /**
    * A Leg is a route between only two waypoints
-   * <p>
-   * Sets List of {@link RouteLeg} objects.
    *
-   * @since 2.0.1
+   * @param legs list of {@link RouteLeg} objects.
+   * @since 2.1.0
    */
   public void setLegs(List<RouteLeg> legs) {
     this.legs = legs;
   }
-
-
 }

mapbox/libjava-services/src/main/java/com/mapbox/services/api/directions/v5/models/DirectionsWaypoint.java

@@ -12,10 +12,17 @@ public class DirectionsWaypoint {
   private String name;
   private double[] location;
 
+  /**
+   * Empty constructor
+   *
+   * @since 2.0.0
+   */
   public DirectionsWaypoint() {
   }
 
   /**
+   * Provides the way name which the waypoint's coordinate is snapped to.
+   *
    * @return String with the name of the way the coordinate snapped to.
    * @since 1.0.0
    */
@@ -24,15 +31,18 @@ public String getName() {
   }
 
   /**
-   * Sets String with the name of the way the coordinate snapped to.
+   * Provide a way name which the waypoint's coordinate is snapped to.
    *
-   * @since 2.0.1
+   * @param name a String with the name of the way the coordinate snapped to.
+   * @since 2.1.0
    */
   public void setName(String name) {
     this.name = name;
   }
 
   /**
+   * an array with two double values reresenting the maneuver locations coordinate.
+   *
    * @return double array of [longitude, latitude] for the snapped coordinate.
    * @since 1.0.0
    */
@@ -43,7 +53,8 @@ public double[] getLocation() {
   /**
    * Sets double array of [longitude, latitude] for the snapped coordinate.
    *
-   * @since 2.0.1
+   * @param location array with the order [longitude, latitude].
+   * @since 2.1.0
    */
   public void setLocation(double[] location) {
     this.location = location;