[android] #3338 - add javadoc annotations package

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

@@ -10,6 +10,20 @@
 import com.mapbox.mapboxsdk.utils.ApiAccess;
 import com.mapbox.mapboxsdk.views.MapView;
 
+/**
+ * Fragment wrapper around a {@link MapView}.
+ * <p>
+ * A Map component in an app. This fragment is the simplest way to place a map in an application.
+ * It's a wrapper around a view of a map to automatically handle the necessary life cycle needs.
+ * Being a fragment, this component can be added to an activity's layout or can dynamically be added
+ * using a FragmentManager.
+ * </p>
+ * <p>
+ * To get a reference to the MapView, use {@link #getMap()}
+ * </p>
+ *
+ * @see #getMap()
+ */
 public class MapFragment extends Fragment {
 
     //

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

@@ -5,10 +5,12 @@
 import com.mapbox.mapboxsdk.views.MapView;
 
 /**
- * Annotation is the most general kind of overlay on top of a map,
- * from which {@link InfoWindow} and {@link Marker} are derived: it manages
- * attachment to a map and identification, but does not require
+ * Annotation is a 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
  * content to be placed at a geographical point.
+ * </p>
  */
 public abstract class Annotation implements Comparable<Annotation> {
 

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

@@ -2,6 +2,10 @@
 
 import android.graphics.Bitmap;
 
+/**
+ * Icon is the visual representation of a {@link Marker} on a {@link com.mapbox.mapboxsdk.views.MapView}.
+ * @see Marker
+ */
 public final class Icon {
     private Bitmap mBitmap;
     private String mId;

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

@@ -22,6 +22,10 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+/**
+ * Factory for creating {@link Icon} objects.
+ * @see Icon
+ */
 public final class IconFactory {
 
     private static final String ICON_ID_PREFIX = "com.mapbox.icons.icon_";

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

@@ -17,19 +17,22 @@
 
 /**
  * <p>
- * A tooltip view. This is a UI element placed over a map at a specific geographic
- * location.
+ * InfoWindow is a tooltip shown when a {@link Marker} is tapped.
+ * </p>
+ * <p>
+ * This is a UI element placed over a map at a specific geographic location.
  * </p>
  */
 public class InfoWindow {
 
     private WeakReference<Marker> mBoundMarker;
     private WeakReference<MapView> mMapView;
+    protected WeakReference<View> mView;
+
     private float mMarkerHeightOffset;
     private float mViewWidthOffset;
     private PointF mCoordinates;
     private boolean mIsVisible;
-    protected WeakReference<View> mView;
 
     @LayoutRes
     private int mLayoutRes;

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

@@ -9,9 +9,10 @@
 import com.mapbox.mapboxsdk.views.MapView;
 
 /**
- * A marker is a map overlay that shows an icon image at a specific
- * geographical location and can be associated with a {@link InfoWindow}
- * that is shown when the marker is tapped.
+ * Marker is an annotation that shows an icon image at a geographical location.
+ * </p>
+ * An {@link InfoWindow} can be shown when a Marker is pressed
+ * <p>
  */
 public final class Marker extends Annotation {
 
@@ -54,6 +55,8 @@ public void hideInfoWindow() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return boolean State of a InfoWindow
      */
     public boolean isInfoWindowShown() {
         return infoWindowShown;
@@ -69,6 +72,8 @@ void setSnippet(String snippet) {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param icon The icon to be used as Marker image
      */
     public void setIcon(@Nullable Icon icon) {
         this.icon = icon;
@@ -84,6 +89,9 @@ void setTitle(String title) {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param mapView The MapView to show the InfoWindow on.
+     * @return infoWindow The infoWindow to show
      */
     public InfoWindow showInfoWindow(@NonNull MapView mapView) {
         setMapView(mapView);
@@ -127,6 +135,8 @@ void setVisible(boolean visible) {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param topOffsetPixels the pixels to have as offset
      */
     public void setTopOffsetPixels(int topOffsetPixels) {
         this.topOffsetPixels = topOffsetPixels;

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

@@ -10,9 +10,7 @@
 
 /**
  * <p>
- * A builder object for the options configuration {@link com.mapbox.mapboxsdk.annotations.Marker} and
- * {@link com.mapbox.mapboxsdk.annotations.InfoWindow}
- * instances on maps.
+ * Builder for composing {@link com.mapbox.mapboxsdk.annotations.Marker} objects.
  * </p>
  *
  * <h3>Example</h3>
@@ -70,6 +68,8 @@ public MarkerOptions() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return Marker The build marker
      */
     public Marker getMarker() {
         return marker;

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

@@ -5,6 +5,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Multipoint is an abstract annotation for combining geographical locations.
+ */
 public abstract class MultiPoint extends Annotation {
 
     private List<LatLng> points;

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

@@ -9,6 +9,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Builder for composing {@link Polygon} objects.
+ */
 public final class PolygonOptions implements Parcelable {
 
     public static final Parcelable.Creator<PolygonOptions> CREATOR
@@ -96,6 +99,8 @@ public int getFillColor() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return Polygon the Polygon to return
      */
     public Polygon getPolygon() {
         return polygon;

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

@@ -8,6 +8,9 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Builder for composing {@link Polyline} objects.
+ */
 public final class PolylineOptions implements Parcelable {
 
 
@@ -83,6 +86,7 @@ public float getAlpha() {
      * Sets the color of the polyline.
      *
      * @param color - the color in ARGB format
+     * @return PolyLineOptions The builder used to build a Polyline
      */
     public PolylineOptions color(int color) {
         polyline.setColor(color);
@@ -95,6 +99,7 @@ public int getColor() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     * @return PolyLine The polyline build by this class.
      */
     public Polyline getPolyline() {
         return polyline;

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

@@ -1,7 +1,7 @@
 package com.mapbox.mapboxsdk.geometry;
 
 /**
- * Implementation of iOS MGLCoordinateBounds
+ * A rectangular geograpical region defined by a south west {@link LatLng} and a north east {@link LatLng}.
  */
 public class CoordinateBounds {
 

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

@@ -1,7 +1,7 @@
 package com.mapbox.mapboxsdk.geometry;
 
 /**
- * Implementation of iOS MKCoordinateRegion
+ * A geographical region defined by a {@link LatLng} and a {@link CoordinateSpan}.
  */
 public class CoordinateRegion {
     private LatLng center;

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

@@ -1,7 +1,7 @@
 package com.mapbox.mapboxsdk.geometry;
 
 /**
- * Implementation of iOS MKCoordinateSpan
+ * A geographical span defined by its latitude and longitude span.
  */
 public class CoordinateSpan {
 

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

@@ -1,7 +1,7 @@
 package com.mapbox.mapboxsdk.geometry;
 
 /**
- * A Latitude, Longitude point.
+ * Describes a latitude, longitude point.
  */
 public interface ILatLng {
     double getLatitude();

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

@@ -1,5 +1,8 @@
 package com.mapbox.mapboxsdk.geometry;
 
+/**
+ * Describes a projection in Mercator meters.
+ */
 public interface IProjectedMeters {
     double getNorthing();
 

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

@@ -10,9 +10,10 @@
 import java.io.Serializable;
 
 /**
+ * A geographical location which contains a single latitude, longitude pair, with
+ * optional altitude.
  * <p>
- * This class is container for a single latitude, longitude pair, with
- * optional altitude. Latitude and longitude are expressed as decimal degrees
+ * Latitude and longitude are expressed as decimal degrees
  * in the WGS84 datum. By default, altitude is 0.0, or sea level.
  * </p>
  * <p>

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

@@ -5,6 +5,9 @@
 
 import java.io.Serializable;
 
+/**
+ * A geographical location which contains a {@link LatLng}, zoom pair.
+ */
 public class LatLngZoom extends LatLng implements Parcelable, Serializable {
 
     public static final Parcelable.Creator<LatLngZoom> CREATOR = new Parcelable.Creator<LatLngZoom>() {

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

@@ -6,10 +6,12 @@
 import java.io.Serializable;
 
 /**
- * ProjectedMeters is an internal representation of longitude, latitude points that
- * have been projected into Mapbox GL's Mercator projection. Instead of decimal
+ * ProjectedMeters is a projection of longitude, latitude points in Mercator meters.
+ * <p>
+ * these have been projected into Mapbox GL's Mercator projection. Instead of decimal
  * degrees, it uses Mercator meters (which are notably not equivalent to SI meters)
  * except at the equator.
+ * </p>
  */
 public class ProjectedMeters implements IProjectedMeters, Parcelable, Serializable {