[android] mapbox#3749 - added javadoc

platform/android/MapboxGLAndroidSDK/src/main/java/com/almeros/android/multitouch/gesturedetectors/package-info.java

@@ -1,4 +1,4 @@
 /**
- * Do not use this package. Used internally by the SDK.
+ * Do not use this package. Internal use only.
  */
 package com.almeros.android.multitouch.gesturedetectors;

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

@@ -6,7 +6,7 @@
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
 /**
- * Annotation is a overlay on top of a {@link MapView},
+ * Annotation is an overlay on top of a {@link MapView},
  * from which {@link Polygon}, {@link Polyline} and {@link Marker} are derived.
  * <p>
  * it manages attachment to a map and identification, but does not require
@@ -55,10 +55,15 @@ public void setId(long id) {
     /**
      * Do not use this method. Used internally by the SDK.
      */
-    public void setMapboxMap(MapboxMap mapView) {
-        this.mapboxMap = mapView;
+    public void setMapboxMap(MapboxMap mapboxMap) {
+        this.mapboxMap = mapboxMap;
     }
 
+    /**
+     * Gets the associated MapboxMap
+     *
+     * @return The MapboxMap
+     */
     protected MapboxMap getMapboxMap() {
         return mapboxMap;
     }

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

@@ -4,6 +4,14 @@
 
 import com.mapbox.mapboxsdk.geometry.LatLng;
 
+/**
+ * Abstract builder class for composing custom Marker objects.
+ * <p/>
+ * Extending this class requires implementing Parceable interface.
+ *
+ * @param <U> Type of the marker to be composed
+ * @param <T> Type of the builder to be used for composing a custom Marker
+ */
 public abstract class BaseMarkerOptions<U extends Marker, T extends BaseMarkerOptions<U, T>> implements Parcelable {
 
     protected LatLng position;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/package-info.java

@@ -1,4 +1,4 @@
 /**
- * This package contains classes to add and manage annotations on your map.
+ * Contains the Mapbox Maps Android Annotation API classes.
  */
 package com.mapbox.mapboxsdk.annotations;

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

@@ -11,6 +11,9 @@
 import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.utils.MathUtils;
 
+/**
+ * Resembles the position, angle, zoom and tilt of the user's viewpoint.
+ */
 public final class CameraPosition implements Parcelable {
 
     public static final Parcelable.Creator<CameraPosition> CREATOR
@@ -28,7 +31,6 @@ public CameraPosition[] newArray(int size) {
         }
     };
 
-
     /**
      * Direction that the camera is pointing in, in degrees clockwise from north.
      */
@@ -68,7 +70,7 @@ public CameraPosition[] newArray(int size) {
 
     @Override
     public int describeContents() {
-        return 0;
+        return hashCode();
     }
 
     @Override
@@ -115,7 +117,7 @@ public int hashCode() {
     }
 
     /**
-     * Builds camera position.
+     * Builder for composing {@link CameraPosition} objects.
      */
     public static final class Builder {
 
@@ -215,7 +217,6 @@ public Builder(double[] values) {
             }
         }
 
-
         /**
          * Sets the direction that the camera is pointing in, in degrees clockwise from north.
          *

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

@@ -2,10 +2,12 @@
 
 import android.support.annotation.NonNull;
 
-import com.mapbox.mapboxsdk.camera.CameraPosition;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 
-public interface  CameraUpdate {
+/**
+ * Interface definition for camera position changes.
+ */
+public interface CameraUpdate {
 
     CameraPosition getCameraPosition(@NonNull MapboxMap mapboxMap);
 

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

@@ -16,13 +16,16 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
+/**
+ * Factory for creating {@link CameraUpdate} objects.
+ */
 public final class CameraUpdateFactory {
 
     /**
      * Returns a CameraUpdate that moves the camera to a specified CameraPosition.
      *
      * @param cameraPosition Camera Position to change to
-     * @return CameraUpdate Final Camera Position data
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate newCameraPosition(@NonNull CameraPosition cameraPosition) {
         return new CameraPositionUpdate(cameraPosition.bearing, cameraPosition.target, cameraPosition.tilt, cameraPosition.zoom);
@@ -32,8 +35,8 @@ public static CameraUpdate newCameraPosition(@NonNull CameraPosition cameraPosit
      * Returns a CameraUpdate that moves the center of the screen to a latitude and longitude
      * specified by a LatLng object. This centers the camera on the LatLng object.
      *
-     * @param latLng
-     * @return
+     * @param latLng Target location to change to
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate newLatLng(@NonNull LatLng latLng) {
         return new CameraPositionUpdate(-1, latLng, -1, -1);
@@ -45,9 +48,9 @@ public static CameraUpdate newLatLng(@NonNull LatLng latLng) {
      * 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.
      *
-     * @param bounds
-     * @param padding
-     * @return
+     * @param bounds  Bounds to match Camera position with
+     * @param padding Padding added to the bounds
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate newLatLngBounds(@NonNull LatLngBounds bounds, int padding) {
         return newLatLngBounds(bounds, padding, padding, padding, padding);
@@ -60,34 +63,36 @@ public static CameraUpdate newLatLngBounds(@NonNull LatLngBounds bounds, int pad
      * 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.
      *
-     * @param bounds
-     * @param paddingLeft
-     * @param paddingTop
-     * @param paddingRight
-     * @param paddingBottom
-     * @return
+     * @param bounds        Bounds to base the Camera position out of
+     * @param paddingLeft   Padding left of the bounds
+     * @param paddingTop    Padding top of the bounds
+     * @param paddingRight  Padding right of the bounds
+     * @param paddingBottom Padding bottom of the bounds
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate newLatLngBounds(@NonNull LatLngBounds bounds, int paddingLeft, int paddingTop, int paddingRight, int paddingBottom) {
         return new CameraBoundsUpdate(bounds, paddingLeft, paddingTop, paddingRight, paddingBottom);
     }
 
     /**
-     * Returns a CameraUpdate that moves the center of the screen to a latitude and longitude specified by a LatLng object, and moves to the given zoom level.
+     * Returns a CameraUpdate that moves the center of the screen to a latitude and longitude specified by a LatLng object,
+     * and moves to the given zoom level.
      *
-     * @param latLng
-     * @param zoom
-     * @return
+     * @param latLng Target location to change to
+     * @param zoom   Zoom level to change to
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate newLatLngZoom(@NonNull LatLng latLng, float zoom) {
         return new CameraPositionUpdate(-1, latLng, -1, zoom);
     }
 
     /**
-     * Returns a CameraUpdate that scrolls the camera over the map, shifting the center of view by the specified number of pixels in the x and y directions.
+     * Returns a CameraUpdate that scrolls the camera over the map,
+     * shifting the center of view by the specified number of pixels in the x and y directions.
      *
-     * @param xPixel
-     * @param yPixel
-     * @return
+     * @param xPixel Amount of pixels to scroll to in x direction
+     * @param yPixel Amount of pixels to scroll to in y direction
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate scrollBy(float xPixel, float yPixel) {
         return new CameraMoveUpdate(xPixel, yPixel);
@@ -96,9 +101,9 @@ public static CameraUpdate scrollBy(float xPixel, float yPixel) {
     /**
      * Returns a CameraUpdate that shifts the zoom level of the current camera viewpoint.
      *
-     * @param amount
-     * @param focus
-     * @return
+     * @param amount Amount of zoom level to change with
+     * @param focus  Focus point of zoom
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate zoomBy(float amount, Point focus) {
         return new ZoomUpdate(amount, focus.x, focus.y);
@@ -107,8 +112,8 @@ public static CameraUpdate zoomBy(float amount, Point focus) {
     /**
      * Returns a CameraUpdate that shifts the zoom level of the current camera viewpoint.
      *
-     * @param amount
-     * @return
+     * @param amount Amount of zoom level to change with
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate zoomBy(float amount) {
         return new ZoomUpdate(ZoomUpdate.ZOOM_BY, amount);
@@ -117,7 +122,7 @@ public static CameraUpdate zoomBy(float amount) {
     /**
      * Returns a CameraUpdate that zooms in on the map by moving the viewpoint's height closer to the Earth's surface. The zoom increment is 1.0.
      *
-     * @return
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate zoomIn() {
         return new ZoomUpdate(ZoomUpdate.ZOOM_IN);
@@ -126,7 +131,7 @@ public static CameraUpdate zoomIn() {
     /**
      * Returns a CameraUpdate that zooms out on the map by moving the viewpoint's height farther away from the Earth's surface. The zoom increment is -1.0.
      *
-     * @return
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate zoomOut() {
         return new ZoomUpdate(ZoomUpdate.ZOOM_OUT);
@@ -135,8 +140,8 @@ public static CameraUpdate zoomOut() {
     /**
      * Returns a CameraUpdate that moves the camera viewpoint to a particular zoom level.
      *
-     * @param zoom
-     * @return
+     * @param zoom Zoom level to change to
+     * @return CameraUpdate Final Camera Position
      */
     public static CameraUpdate zoomTo(float zoom) {
         return new ZoomUpdate(ZoomUpdate.ZOOM_TO, zoom);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/package-info.java

@@ -1,4 +1,4 @@
 /**
- * This package contains the Camera API classes which are used to control the user's viewpoint of the map.
+ * Contains the Mapbox Maps Android Camera API classes.
  */
 package com.mapbox.mapboxsdk.camera;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/package-info.java

@@ -1,4 +1,4 @@
 /**
- * This package contains multiple map related constants classes.
+ * Contains the Mapbox Maps Android Constant API classes.
  */
 package com.mapbox.mapboxsdk.constants;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java

@@ -9,7 +9,7 @@
 /**
  * <p>
  * A {@code IconBitmapChangedException} is thrown by {@link MapView} when a {@link Marker} is added
- * that has a {@link Icon} with a {@link Bitmap} that has been modified.
+ * that has a {@link Icon} with a {@link Bitmap} that has been modified since the creation of the Icon.
  * </p>
  * You cannot modify a {@code Icon} after it has been added to the map in a {@code Marker}
  *

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidAccessTokenException.java

@@ -5,7 +5,7 @@
 import com.mapbox.mapboxsdk.maps.MapView;
 
 /**
- * A {@code InvalidAccessTokenException} is thrown by {@link MapView} when there is either no access
+ * A {@code InvalidAccessTokenException} is thrown by {@link com.mapbox.mapboxsdk.maps.MapboxMap} when there is either no access
  * token set before {@link MapView#onCreate(Bundle)} or an invalid access token is set in {@link MapView#setAccessToken(String)}
  *
  * @see MapView#onCreate(Bundle)

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java

@@ -1,8 +1,12 @@
 package com.mapbox.mapboxsdk.exceptions;
 
+/**
+ * A InvalidLatLngBoundsException is thrown by {@link com.mapbox.mapboxsdk.geometry.LatLngBounds}
+ * when there aren't enough {@link com.mapbox.mapboxsdk.geometry.LatLng} to create a bounds.
+ */
 public class InvalidLatLngBoundsException extends RuntimeException {
 
     public InvalidLatLngBoundsException(int latLngsListSize) {
-        super("Cannot create a LatLngBounds from " + latLngsListSize +" items");
+        super("Cannot create a LatLngBounds from " + latLngsListSize + " items");
     }
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java

@@ -6,7 +6,7 @@
 /**
  * <p>
  * A {@code TooManyIconsException} is thrown by {@link IconFactory} when it
- * cannot create a {@link Icon} because there are already too many.
+ * cannot create a {@link Icon} because there are already too many icons created.
  * </p>
  * You should try to reuse Icon objects whenever possible.
  *

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/package-info.java

@@ -1,4 +1,4 @@
 /**
- * This package contains map specific exception classes.
+ * Contains the Mapbox Maps Android Exception API classes.
  */
 package com.mapbox.mapboxsdk.exceptions;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java

@@ -10,7 +10,7 @@
 import java.util.List;
 
 /**
- * An immutable class representing a latitude/longitude aligned rectangle.
+ * A geographical area representing a latitude/longitude aligned rectangle.
  */
 public class LatLngBounds implements Parcelable {
 
@@ -132,8 +132,8 @@ static LatLngBounds fromLatLngs(final List<? extends ILatLng> latLngs) {
         return new LatLngBounds(maxLat, maxLon, minLat, minLon);
     }
 
-    public LatLng[] toLatLngs(){
-        return new LatLng[]{new LatLng(mLatNorth,mLonEast),new LatLng(mLatSouth,mLonWest)};
+    public LatLng[] toLatLngs() {
+        return new LatLng[]{new LatLng(mLatNorth, mLonEast), new LatLng(mLatSouth, mLonWest)};
     }
 
     /**
@@ -221,9 +221,9 @@ public LatLngBounds intersect(LatLngBounds box) {
      * Returns a new LatLngBounds that is the intersection of this with another LatLngBounds
      *
      * @param northLatitude Northern Longitude
-     * @param eastLongitude   Eastern Latitude
+     * @param eastLongitude Eastern Latitude
      * @param southLatitude Southern Longitude
-     * @param westLongitude   Western Latitude
+     * @param westLongitude Western Latitude
      * @return LatLngBounds
      */
     public LatLngBounds intersect(double northLatitude, double eastLongitude, double southLatitude, double westLongitude) {
@@ -272,6 +272,9 @@ private static LatLngBounds readFromParcel(final Parcel in) {
         return new LatLngBounds(lonNorth, latEast, lonSouth, latWest);
     }
 
+    /**
+     * Builder for composing LatLngBounds objects.
+     */
     public static final class Builder {
 
         private List<LatLng> mLatLngList;