Adds missing docs and cleans things up in static map module (#690)

* Adds missing docs and cleans things up in static map module

* made Osana’s suggested change

Author: Cameron Mace

services-core/src/main/java/com/mapbox/core/utils/ColorUtils.java

@@ -0,0 +1,33 @@
+package com.mapbox.core.utils;
+
+import java.awt.Color;
+
+/**
+ * Utils class for assisting with color transformations and other operations being done on colors.
+ *
+ * @since 3.0.0
+ */
+public final class ColorUtils {
+
+  private ColorUtils() {
+    // No Instance.
+  }
+
+  /**
+   * Converts a {@link Color} object to a hex string that can then be used in a URL when making API
+   * request. Note that this does <b>Not</b> add the hex key before the string.
+   *
+   * @param color the color which needs to be converted
+   * @return the hex color value as a string
+   * @since 3.0.0
+   */
+  public static String toHexString(Color color) {
+    String hexColor
+      = String.format("%02X%02X%02X", color.getRed(), color.getGreen(), color.getBlue());
+
+    if (hexColor.length() < 6) {
+      hexColor = "000000".substring(0, 6 - hexColor.length()) + hexColor;
+    }
+    return hexColor;
+  }
+}

services-staticmap/src/main/java/com/mapbox/api/staticmap/v1/MapboxStaticMap.java

@@ -4,24 +4,22 @@
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
-
 import com.google.auto.value.AutoValue;
+import com.mapbox.api.staticmap.v1.models.StaticMarkerAnnotation;
 import com.mapbox.api.staticmap.v1.models.StaticPolylineAnnotation;
 import com.mapbox.core.constants.Constants;
-import com.mapbox.api.staticmap.v1.models.StaticMarkerAnnotation;
-import com.mapbox.geojson.GeoJson;
-import com.mapbox.geojson.Point;
+import com.mapbox.core.exceptions.ServicesException;
 import com.mapbox.core.utils.MapboxUtils;
 import com.mapbox.core.utils.TextUtils;
-import com.mapbox.core.exceptions.ServicesException;
+import com.mapbox.geojson.GeoJson;
+import com.mapbox.geojson.Point;
+import okhttp3.HttpUrl;
 
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Locale;
 
-import okhttp3.HttpUrl;
-
 /**
  * Static maps are standalone images that can be displayed in your mobile app without the aid of a
  * mapping library like the Mapbox Android SDK. They look like an embedded map without interactivity
@@ -37,6 +35,9 @@
 @AutoValue
 public abstract class MapboxStaticMap {
 
+  private static final String BEFORE_LAYER = "before_layer";
+  private static final String CAMERA_AUTO = "auto";
+
   @Nullable
   abstract String accessToken();
 
@@ -125,11 +126,11 @@ public HttpUrl url() {
       urlBuilder.addPathSegment(TextUtils.join(",", annotations.toArray()));
     }
 
-    urlBuilder.addPathSegment(cameraAuto() ? StaticMapCriteria.CAMERA_AUTO
+    urlBuilder.addPathSegment(cameraAuto() ? CAMERA_AUTO
       : generateLocationPathSegment());
 
     if (beforeLayer() != null) {
-      urlBuilder.addQueryParameter(StaticMapCriteria.BEFORE_LAYER, beforeLayer());
+      urlBuilder.addQueryParameter(BEFORE_LAYER, beforeLayer());
     }
     if (!attribution()) {
       urlBuilder.addQueryParameter("attribution", "false");
@@ -176,7 +177,7 @@ public static Builder builder() {
       .styleId(StaticMapCriteria.STREET_STYLE)
       .baseUrl(Constants.BASE_API_URL)
       .user(Constants.MAPBOX_USER)
-      .cameraPoint(Point.fromLngLat(0d,0d))
+      .cameraPoint(Point.fromLngLat(0d, 0d))
       .cameraAuto(false)
       .attribution(true)
       .width(250)
@@ -398,6 +399,13 @@ public abstract Builder staticPolylineAnnotations(
 
     abstract MapboxStaticMap autoBuild();
 
+    /**
+     * This uses the provided parameters set using the {@link Builder} and creates a new
+     * {@link MapboxStaticMap} object.
+     *
+     * @return a new instance of {@link MapboxStaticMap}
+     * @since 2.1.0
+     */
     public MapboxStaticMap build() {
       MapboxStaticMap staticMap = autoBuild();
 
@@ -406,8 +414,7 @@ public MapboxStaticMap build() {
           + " token.");
       }
 
-
-      if (staticMap.styleId() == null || staticMap.styleId().isEmpty()) {
+      if (staticMap.styleId().isEmpty()) {
         throw new ServicesException("You need to set a map style.");
       }
       return staticMap;

services-staticmap/src/main/java/com/mapbox/api/staticmap/v1/StaticMapCriteria.java

@@ -6,35 +6,121 @@
 
 import java.lang.annotation.Retention;
 
-
+/**
+ * Constant values related to the Static Map API can be found in this class.
+ *
+ * @since 3.0.0
+ */
 public final class StaticMapCriteria {
 
+  /**
+   * The Static Maps marker shape and size will be small.
+   *
+   * @since 3.0.0
+   */
   public static final String SMALL_PIN = "pin-s";
 
+  /**
+   * The Static Maps marker shape and size will be medium.
+   *
+   * @since 3.0.0
+   */
   public static final String MEDIUM_PIN = "pin-m";
 
+  /**
+   * The Static Maps marker shape and size will be large.
+   *
+   * @since 3.0.0
+   */
   public static final String LARGE_PIN = "pin-l";
 
-  static final String CAMERA_AUTO = "auto";
-
-  static final String BEFORE_LAYER = "before_layer";
-
+  /**
+   * Mapbox Streets is a comprehensive, general-purpose map that emphasizes accurate, legible
+   * styling of road and transit networks.
+   *
+   * @since 3.0.0
+   */
   public static final String STREET_STYLE = "streets-v10";
+
+  /**
+   * Mapbox Outdoors is a general-purpose map with curated tilesets and specialized styling tailored
+   * to hiking, biking, and the most adventurous use cases.
+   *
+   * @since 3.0.0
+   */
   public static final String OUTDOORS_STYLE = "outdoors-v10";
+
+
+  /**
+   * Mapbox Light style's a subtle, full-featured map designed to provide geographic context while
+   * highlighting the data on your analytics dashboard, data visualization, or data overlay.
+   *
+   * @since 3.0.0
+   */
   public static final String LIGHT_STYLE = "light-v9";
+
+  /**
+   * Mapbox Dark style's a subtle, full-featured map designed to provide geographic context while
+   * highlighting the data on your analytics dashboard, data visualization, or data overlay.
+   *
+   * @since 3.0.0
+   */
   public static final String DARK_STYLE = "dark-v9";
+
+  /**
+   * Mapbox Satellite is our full global base map that is perfect as a blank canvas or an overlay
+   * for your own data.
+   *
+   * @since 3.0.0
+   */
   public static final String SATELLITE_STYLE = "satellite-v9";
+
+  /**
+   * Mapbox Satellite Streets combines our Mapbox Satellite with vector data from Mapbox Streets.
+   * The comprehensive set of road, label, and POI information brings clarity and context to the
+   * crisp detail in our high-resolution satellite imagery.
+   *
+   * @since 3.0.0
+   */
   public static final String SATELLITE_STREETS_STYLE = "satellite-streets-v10";
 
+  /**
+   * Navigation specific style that shows only the necessary information while a user is driving.
+   *
+   * @since 3.0.0
+   */
   public static final String NAVIGATION_PREVIEW_DAY = "navigation-preview-day-v2";
+
+  /**
+   * Navigation specific style that shows only the necessary information while a user is driving.
+   *
+   * @since 3.0.0
+   */
   public static final String NAVIGATION_PREVIEW_NIGHT = "navigation-preview-night-v2";
+
+  /**
+   * Navigation specific style that shows only the necessary information while a user is driving.
+   *
+   * @since 3.0.0
+   */
   public static final String NAVIGATION_GUIDANCE_DAY = "navigation-guidance-day-v2";
+
+  /**
+   * Navigation specific style that shows only the necessary information while a user is driving.
+   *
+   * @since 3.0.0
+   */
   public static final String NAVIGATION_GUIDANCE_NIGHT = "navigation-guidance-night-v2";
 
   private StaticMapCriteria() {
-    // Empty private constructor since only static methods are found inside class.
+    throw new AssertionError("No Instances.");
   }
 
+  /**
+   * Retention policy for the pin parameter in the Static Map Marker Annotation API.
+   *
+   * @since 3.0.0
+   */
   @Retention(SOURCE)
   @StringDef( {
     SMALL_PIN,

services-staticmap/src/main/java/com/mapbox/api/staticmap/v1/models/StaticMarkerAnnotation.java

@@ -1,11 +1,16 @@
 package com.mapbox.api.staticmap.v1.models;
 
+import static android.support.annotation.RestrictTo.Scope.LIBRARY;
+import static com.mapbox.core.utils.ColorUtils.toHexString;
+
 import android.support.annotation.Nullable;
+import android.support.annotation.RestrictTo;
 import com.google.auto.value.AutoValue;
 import com.mapbox.api.staticmap.v1.StaticMapCriteria;
-import com.mapbox.geojson.Point;
-import com.mapbox.core.utils.TextUtils;
+import com.mapbox.api.staticmap.v1.StaticMapCriteria.MarkerCriteria;
 import com.mapbox.core.exceptions.ServicesException;
+import com.mapbox.core.utils.TextUtils;
+import com.mapbox.geojson.Point;
 
 import java.awt.Color;
 import java.util.Locale;
@@ -32,6 +37,13 @@ public static Builder builder() {
       .name(StaticMapCriteria.MEDIUM_PIN);
   }
 
+  /**
+   * <em>Used Internally</em>
+   *
+   * @return a String representing the marker part of the URL
+   * @since 2.1.0
+   */
+  @RestrictTo(LIBRARY)
   public String url() {
     String url;
     if (iconUrl() != null) {
@@ -86,7 +98,7 @@ public abstract static class Builder {
      * @return this builder for chaining options together
      * @since 2.1.0
      */
-    public abstract Builder name(@StaticMapCriteria.MarkerCriteria String name);
+    public abstract Builder name(@MarkerCriteria String name);
 
     /**
      * Marker symbol. Options are an alphanumeric label "a" through "z", "0" through  "99", or a
@@ -96,7 +108,6 @@ public abstract static class Builder {
      * @return this builder for chaining options together
      * @since 2.1.0
      */
-    // TODO place a filter on only accepted labels
     public abstract Builder label(String label);
 
     /**
@@ -118,10 +129,25 @@ public abstract static class Builder {
      */
     public abstract Builder lnglat(Point lnglat);
 
+    /**
+     * a percent-encoded URL for the marker image. Can be of type PNG or JPG.
+     *
+     * @param url an encoded URL for the marker image
+     * @return this builder for chaining options together
+     * @since 2.1.0
+     */
     public abstract Builder iconUrl(@Nullable String url);
 
     abstract StaticMarkerAnnotation autoBuild();
 
+    /**
+     * Build a new marker instance and pass it into
+     * {@link com.mapbox.api.staticmap.v1.MapboxStaticMap} in order to use it during your Static Map
+     * API request.
+     *
+     * @return a new instance of {@link StaticMarkerAnnotation}
+     * @since 2.1.0
+     */
     public StaticMarkerAnnotation build() {
       StaticMarkerAnnotation marker = autoBuild();
       if (marker.lnglat() == null) {
@@ -131,13 +157,4 @@ public StaticMarkerAnnotation build() {
       return marker;
     }
   }
-
-  // TODO move to utils class
-  public static final String toHexString(Color color) {
-    String hexColour = Integer.toHexString(color.getRGB() & 0xffffff);
-    if (hexColour.length() < 6) {
-      hexColour = "000000".substring(0, 6 - hexColour.length()) + hexColour;
-    }
-    return hexColour;
-  }
 }

services-staticmap/src/main/java/com/mapbox/api/staticmap/v1/models/StaticPolylineAnnotation.java

@@ -1,9 +1,13 @@
 package com.mapbox.api.staticmap.v1.models;
 
+import static android.support.annotation.RestrictTo.Scope.LIBRARY;
+import static com.mapbox.core.utils.ColorUtils.toHexString;
+
 import android.support.annotation.FloatRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 
+import android.support.annotation.RestrictTo;
 import com.google.auto.value.AutoValue;
 import com.mapbox.api.staticmap.v1.MapboxStaticMap;
 import com.mapbox.geojson.utils.PolylineUtils;
@@ -32,6 +36,13 @@ public static Builder builder() {
     return new AutoValue_StaticPolylineAnnotation.Builder();
   }
 
+  /**
+   * <em>Used Internally</em>
+   *
+   * @return a String representing the marker part of the URL
+   * @since 2.1.0
+   */
+  @RestrictTo(LIBRARY)
   public String url() {
     StringBuilder sb = new StringBuilder();
 
@@ -142,18 +153,9 @@ public abstract static class Builder {
      * {@link StaticMarkerAnnotation} object which can be passed into the {@link MapboxStaticMap}
      * request.
      *
-     * @return a new instance of StaticPolylineAnnotation
+     * @return a new instance of {@link StaticPolylineAnnotation}
      * @since 2.1.0
      */
     public abstract StaticPolylineAnnotation build();
   }
-
-  // TODO move to utils class
-  public static final String toHexString(Color color) {
-    String hexColour = Integer.toHexString(color.getRGB() & 0xffffff);
-    if (hexColour.length() < 6) {
-      hexColour = "000000".substring(0, 6 - hexColour.length()) + hexColour;
-    }
-    return hexColour;
-  }
 }

services-staticmap/src/main/java/com/mapbox/api/staticmap/v1/models/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Package containing all the Static Map annotations avaliable.
+ *
+ * @since 3.0.0
+ */
+package com.mapbox.api.staticmap.v1.models;