[android] - revisit public API javadoc

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java

@@ -1,6 +1,5 @@
 package com.mapbox.mapboxsdk;
 
-import android.app.Application;
 import android.content.Context;
 import android.net.ConnectivityManager;
 import android.net.NetworkInfo;
@@ -17,10 +16,10 @@
 import com.mapbox.services.android.telemetry.location.LocationEnginePriority;
 
 /**
- * The entry point of the Mapbox Android SDK.
+ * The entry point to initialize the Mapbox Android SDK.
  * <p>
  * Obtain a reference by calling {@link #getInstance(Context, String)}. Usually this class is configured in
- * {@link Application#onCreate()} and is responsible for the active access token, application context, and
+ * Application#onCreate() and is responsible for the active access token, application context, and
  * connectivity state.
  * </p>
  */
@@ -97,6 +96,8 @@ private static void validateAccessToken() throws MapboxConfigurationException {
 
   /**
    * Application context
+   *
+   * @return the application context
    */
   public static Context getApplicationContext() {
     return INSTANCE.context;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java

@@ -23,7 +23,7 @@
 /**
  * Factory for creating Icons from bitmap images.
  * <p>
- * {@link Icon} is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}.
+ * icon is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}.
  * </p>
  *
  * @see Icon
@@ -42,6 +42,12 @@ public final class IconFactory {
 
   private int nextId = 0;
 
+  /**
+   * Get a single instance of IconFactory.
+   *
+   * @param context the context to derive the application context from
+   * @return the single instance of IconFactory
+   */
   public static synchronized IconFactory getInstance(@NonNull Context context) {
     if (instance == null) {
       instance = new IconFactory(context.getApplicationContext());
@@ -71,10 +77,10 @@ private IconFactory(@NonNull Context context) {
   }
 
   /**
-   * Creates an {@link Icon} from a given Bitmap image.
+   * Creates an icon from a given Bitmap image.
    *
    * @param bitmap image used for creating the Icon.
-   * @return The {@link Icon} using the given Bitmap image.
+   * @return The icon using the given Bitmap image.
    */
   public Icon fromBitmap(@NonNull Bitmap bitmap) {
     if (nextId < 0) {
@@ -85,10 +91,10 @@ public Icon fromBitmap(@NonNull Bitmap bitmap) {
   }
 
   /**
-   * Create an {@link Icon} using the resource ID of a Bitmap image.
+   * Create an icon using the resource ID of a Bitmap image.
    *
    * @param resourceId The resource ID of a Bitmap image.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The icon that was loaded from the asset or {@code null} if failed to load.
    */
   public Icon fromResource(@DrawableRes int resourceId) {
     Drawable drawable = ContextCompat.getDrawable(context, resourceId);
@@ -101,9 +107,9 @@ public Icon fromResource(@DrawableRes int resourceId) {
   }
 
   /**
-   * Provides an {@link Icon} using the default marker icon used for {@link Marker}.
+   * Provides an icon using the default marker icon used for {@link Marker}.
    *
-   * @return An {@link Icon} with the default {@link Marker} icon.
+   * @return An icon with the default {@link Marker} icon.
    */
   public Icon defaultMarker() {
     if (defaultMarker == null) {
@@ -113,9 +119,9 @@ public Icon defaultMarker() {
   }
 
   /**
-   * Provides an {@link Icon} using the default marker icon used for {@link MarkerView}.
+   * Provides an icon using the default marker icon used for {@link MarkerView}.
    *
-   * @return An {@link Icon} with the default {@link MarkerView} icon.
+   * @return An icon with the default {@link MarkerView} icon.
    */
   public Icon defaultMarkerView() {
     if (defaultMarkerView == null) {
@@ -130,10 +136,10 @@ private Icon fromInputStream(@NonNull InputStream is) {
   }
 
   /**
-   * Creates an {@link Icon} using the name of a Bitmap image in the assets directory.
+   * Creates an Icon using the name of a Bitmap image in the assets directory.
    *
    * @param assetName The name of a Bitmap image in the assets directory.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The Icon that was loaded from the asset or null if failed to load.
    */
   public Icon fromAsset(@NonNull String assetName) {
     InputStream is;
@@ -146,10 +152,10 @@ public Icon fromAsset(@NonNull String assetName) {
   }
 
   /**
-   * Creates an {@link Icon} using the absolute file path of a Bitmap image.
+   * Creates an Icon using the absolute file path of a Bitmap image.
    *
    * @param absolutePath The absolute path of the Bitmap image.
-   * @return The {@link Icon} that was loaded from the absolute path or {@code null} if failed to
+   * @return The Icon that was loaded from the absolute path or null if failed to
    * load.
    */
   public Icon fromPath(@NonNull String absolutePath) {
@@ -158,11 +164,11 @@ public Icon fromPath(@NonNull String absolutePath) {
   }
 
   /**
-   * Create an {@link Icon} using the name of a Bitmap image file located in the internal storage.
-   * In particular, this calls {@link Context#openFileInput(String)}.
+   * Create an Icon using the name of a Bitmap image file located in the internal storage.
+   * In particular, this calls Context#openFileInput(String).
    *
    * @param fileName The name of the Bitmap image file.
-   * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load.
+   * @return The Icon that was loaded from the asset or null if failed to load.
    * @see <a href="https://developer.android.com/guide/topics/data/data-storage.html#filesInternal">
    * Using the Internal Storage</a>
    */
@@ -177,12 +183,11 @@ public Icon fromFile(@NonNull String fileName) {
   }
 
   /**
-   * Create an {@link Icon} using a previously created icon identifier along with a provided
-   * Bitmap.
+   * Create an Icon using a previously created icon identifier along with a provided Bitmap.
    *
-   * @param iconId The {@link Icon} identifier you'd like to recreate.
+   * @param iconId The Icon identifier you'd like to recreate.
    * @param bitmap a Bitmap used to replace the current one.
-   * @return The {@link Icon} using the new Bitmap.
+   * @return The Icon using the new Bitmap.
    */
   public static Icon recreate(@NonNull String iconId, @NonNull Bitmap bitmap) {
     return new Icon(iconId, bitmap);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java

@@ -532,10 +532,11 @@ public void invalidateViewMarkersInVisibleRegion() {
   }
 
   /**
-   * When the provided {@link MarkerView} is clicked on by a user, we check if a custom click
-   * event has been created and if not, display a {@link InfoWindow}.
+   * When the provided MarkerView is clicked on by a user, we check if a custom click
+   * event has been created and if not, display a InfoWindow.
    *
-   * @param markerView that the click event occurred.
+   * @param markerView that the click event occurred
+   * @return true if the marker view click has been handled, false if not
    */
   public boolean onClickMarkerView(MarkerView markerView) {
     boolean clickHandled = false;
@@ -560,9 +561,9 @@ public boolean onClickMarkerView(MarkerView markerView) {
   }
 
   /**
-   * Handles the {@link MarkerView}'s info window offset.
+   * Handles the MarkerView info window offset.
    *
-   * @param marker that we are ensuring info window offset.
+   * @param marker that we are ensuring info window offset
    */
   public void ensureInfoWindowOffset(MarkerView marker) {
     View view = null;
@@ -612,7 +613,7 @@ public void addOnMarkerViewAddedListener(MarkerView markerView, OnMarkerViewAdde
   }
 
   /**
-   * Default MarkerViewAdapter used for base class of {@link MarkerView} to adapt a MarkerView to
+   * Default MarkerViewAdapter used for base class of MarkerView to adapt a MarkerView to
    * an ImageView.
    */
   private static class ImageMarkerViewAdapter extends MapboxMap.MarkerViewAdapter<MarkerView> {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java

@@ -3,6 +3,7 @@
 import android.content.res.TypedArray;
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.support.annotation.FloatRange;
 
 import com.mapbox.mapboxsdk.R;
 import com.mapbox.mapboxsdk.constants.MapboxConstants;
@@ -166,14 +167,14 @@ public static final class Builder {
     private double zoom = -1;
 
     /**
-     * Creates an empty builder.
+     * Create an empty builder.
      */
     public Builder() {
       super();
     }
 
     /**
-     * Create Builder with an existing CameraPosition data.
+     * Create a builder with an existing CameraPosition data.
      *
      * @param previous Existing CameraPosition values to use
      */
@@ -188,7 +189,7 @@ public Builder(CameraPosition previous) {
     }
 
     /**
-     * Create Builder with an existing CameraPosition data.
+     * Create a builder with an existing CameraPosition data.
      *
      * @param typedArray TypedArray containing attribute values
      */
@@ -205,7 +206,7 @@ public Builder(TypedArray typedArray) {
     }
 
     /**
-     * Create Builder from an existing CameraPositionUpdate update.
+     * Create a builder from an existing CameraPositionUpdate update.
      *
      * @param update Update containing camera options
      */
@@ -220,7 +221,7 @@ public Builder(CameraUpdateFactory.CameraPositionUpdate update) {
     }
 
     /**
-     * Create Builder from an existing CameraPositionUpdate update.
+     * Create builder from an existing CameraPositionUpdate update.
      *
      * @param update Update containing camera options
      */
@@ -235,7 +236,7 @@ public Builder(CameraUpdateFactory.ZoomUpdate update) {
      * Sets the direction that the camera is pointing in, in degrees clockwise from north.
      *
      * @param bearing Bearing
-     * @return Builder
+     * @return this
      */
     public Builder bearing(double bearing) {
       double direction = bearing;
@@ -252,48 +253,53 @@ public Builder bearing(double bearing) {
     }
 
     /**
-     * Builds a CameraPosition.
+     * Sets the location where the camera is pointing at.
      *
-     * @return CameraPosition
-     */
-    public CameraPosition build() {
-      return new CameraPosition(target, zoom, tilt, bearing);
-    }
-
-    /**
-     * Sets the location that the camera is pointing at.
-     *
-     * @param location Location
-     * @return Builder
+     * @param location target of the camera
+     * @return this
      */
     public Builder target(LatLng location) {
       this.target = location;
       return this;
     }
 
     /**
-     * Set the tilt in degrees
+     * Set the tilt of the camera in degrees
      * <p>
-     * value is clamped to 0 and 60.
+     * value is clamped to {@link MapboxConstants#MINIMUM_TILT} and {@link MapboxConstants#MAXIMUM_TILT}.
      * </p>
      *
-     * @param tilt Tilt value
-     * @return Builder
+     * @param tilt Tilt value of the camera
+     * @return this
      */
-    public Builder tilt(double tilt) {
+    public Builder tilt(@FloatRange(from = MapboxConstants.MINIMUM_TILT,
+      to = MapboxConstants.MAXIMUM_TILT) double tilt) {
       this.tilt = MathUtils.clamp(tilt, MapboxConstants.MINIMUM_TILT, MapboxConstants.MAXIMUM_TILT);
       return this;
     }
 
     /**
-     * Set the zoom
+     * Set the zoom of the camera
+     * <p>
+     * Zoom ranges from {@link MapboxConstants#MINIMUM_ZOOM} to {@link MapboxConstants#MAXIMUM_ZOOM}
+     * </p>
      *
-     * @param zoom Zoom value
-     * @return Builder
+     * @param zoom Zoom value of the camera
+     * @return this
      */
-    public Builder zoom(double zoom) {
+    public Builder zoom(@FloatRange(from = MapboxConstants.MINIMUM_ZOOM,
+      to = MapboxConstants.MAXIMUM_ZOOM) double zoom) {
       this.zoom = zoom;
       return this;
     }
+
+    /**
+     * Builds the CameraPosition.
+     *
+     * @return CameraPosition
+     */
+    public CameraPosition build() {
+      return new CameraPosition(target, zoom, tilt, bearing);
+    }
   }
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java

@@ -5,10 +5,16 @@
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
 /**
- * Interface definition for camera position changes.
+ * Interface definition for camera updates.
  */
 public interface CameraUpdate {
 
+  /**
+   * Get the camera position from the camera update.
+   *
+   * @param mapboxMap Map object to build the position from
+   * @return the camera position from the implementing camera update
+   */
   CameraPosition getCameraPosition(@NonNull MapboxMap mapboxMap);
 
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java

@@ -42,7 +42,7 @@ public static CameraUpdate newLatLng(@NonNull LatLng latLng) {
   }
 
   /**
-   * Returns a {@link CameraUpdate} that transforms the camera such that the specified
+   * Returns a CameraUpdate that transforms the camera such that the specified
    * latitude/longitude bounds are centered on screen at the greatest possible zoom level.
    * You can specify padding, in order to inset the bounding box from the map view's edges.
    * The returned CameraUpdate has a bearing of 0 and a tilt of 0.
@@ -56,7 +56,7 @@ public static CameraUpdate newLatLngBounds(@NonNull LatLngBounds bounds, int pad
   }
 
   /**
-   * Returns a {@link CameraUpdate} that transforms the camera such that the specified
+   * Returns a CameraUpdate that transforms the camera such that the specified
    * latitude/longitude bounds are centered on screen at the greatest possible zoom level.
    * You can specify padding, in order to inset the bounding box from the map view's edges.
    * The returned CameraUpdate has a bearing of 0 and a tilt of 0.

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java

@@ -2,23 +2,27 @@
 
 import android.support.annotation.IntDef;
 
+import com.mapbox.mapboxsdk.maps.MapboxMap;
 import com.mapbox.mapboxsdk.maps.widgets.MyLocationView;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * MyBearingTracking exposes different types bearing tracking modes.
+ * MyBearingTracking exposes different types of bearing tracking modes.
+ * <p>
+ * These modes visualise the user direction by extracting the direction from either sensor or location data.
+ * </p>
+ * <p>
+ * Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}.
+ * </p>
  *
  * @see com.mapbox.mapboxsdk.maps.TrackingSettings#setMyBearingTrackingMode(int)
  * @see MyLocationView#setMyBearingTrackingMode(int)
  */
 public class MyBearingTracking {
 
-  /**
-   * Indicates that the parameter accepts one of the values from MyBearingTracking.
-   */
-  @IntDef( {NONE, COMPASS, GPS, /**COMBINED**/})
+  @IntDef( {NONE, COMPASS, GPS})
   @Retention(RetentionPolicy.SOURCE)
   public @interface Mode {
   }