From fabc457adf04977bd73fd115b9e19383a89402f3 Mon Sep 17 00:00:00 2001
From: Tobrun <tobrun@mapbox.com>
Date: Mon, 18 Jan 2016 13:26:23 +0100
Subject: [android] #3338 - add javadoc annotations package

---
 .../src/main/java/com/mapbox/mapboxsdk/MapFragment.java  | 14 ++++++++++++++
 .../com/mapbox/mapboxsdk/annotations/Annotation.java     |  8 +++++---
 .../main/java/com/mapbox/mapboxsdk/annotations/Icon.java |  4 ++++
 .../com/mapbox/mapboxsdk/annotations/IconFactory.java    |  4 ++++
 .../com/mapbox/mapboxsdk/annotations/InfoWindow.java     |  9 ++++++---
 .../java/com/mapbox/mapboxsdk/annotations/Marker.java    | 16 +++++++++++++---
 .../com/mapbox/mapboxsdk/annotations/MarkerOptions.java  |  6 +++---
 .../com/mapbox/mapboxsdk/annotations/MultiPoint.java     |  3 +++
 .../com/mapbox/mapboxsdk/annotations/PolygonOptions.java |  5 +++++
 .../mapbox/mapboxsdk/annotations/PolylineOptions.java    |  5 +++++
 .../com/mapbox/mapboxsdk/geometry/CoordinateBounds.java  |  2 +-
 .../com/mapbox/mapboxsdk/geometry/CoordinateRegion.java  |  2 +-
 .../com/mapbox/mapboxsdk/geometry/CoordinateSpan.java    |  2 +-
 .../main/java/com/mapbox/mapboxsdk/geometry/ILatLng.java |  2 +-
 .../com/mapbox/mapboxsdk/geometry/IProjectedMeters.java  |  3 +++
 .../main/java/com/mapbox/mapboxsdk/geometry/LatLng.java  |  5 +++--
 .../java/com/mapbox/mapboxsdk/geometry/LatLngZoom.java   |  3 +++
 .../com/mapbox/mapboxsdk/geometry/ProjectedMeters.java   |  6 ++++--
 18 files changed, 79 insertions(+), 20 deletions(-)

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/MapFragment.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/MapFragment.java
index 98d0f79656..5725989964 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/MapFragment.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/MapFragment.java
@@ -10,6 +10,20 @@ import android.view.ViewGroup;
 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 {
 
     //
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
index bf89998788..813e489e94 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java
@@ -5,10 +5,12 @@ import android.support.annotation.NonNull;
 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> {
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java
index d7e28dde73..b9691914e2 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Icon.java
@@ -2,6 +2,10 @@ package com.mapbox.mapboxsdk.annotations;
 
 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;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java
index 8d58866acd..bee4ec47c5 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/IconFactory.java
@@ -22,6 +22,10 @@ import java.io.FileNotFoundException;
 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_";
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java
index 2ace201c9a..696301cf54 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/InfoWindow.java
@@ -17,19 +17,22 @@ import java.lang.ref.WeakReference;
 
 /**
  * <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;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java
index 8b4b66a2a3..3463801448 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java
@@ -9,9 +9,10 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 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 final class Marker extends Annotation {
 
     /**
      * 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 @@ public final class Marker extends Annotation {
 
     /**
      * 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 @@ public final class Marker extends Annotation {
 
     /**
      * 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 @@ public final class Marker extends Annotation {
 
     /**
      * 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;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java
index 69e8b03bda..a83a6991b2 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerOptions.java
@@ -10,9 +10,7 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 
 /**
  * <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 final class MarkerOptions implements Parcelable {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return Marker The build marker
      */
     public Marker getMarker() {
         return marker;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java
index 5c1dfb119f..d2aaea1d17 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MultiPoint.java
@@ -5,6 +5,9 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 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;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java
index c716d10edf..30847807b9 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolygonOptions.java
@@ -9,6 +9,9 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 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 final class PolygonOptions implements Parcelable {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return Polygon the Polygon to return
      */
     public Polygon getPolygon() {
         return polygon;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java
index d48858c7d9..1e625c10fc 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/PolylineOptions.java
@@ -8,6 +8,9 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 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 final class PolylineOptions implements Parcelable {
      * 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 final class PolylineOptions implements Parcelable {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     * @return PolyLine The polyline build by this class.
      */
     public Polyline getPolyline() {
         return polyline;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateBounds.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateBounds.java
index 1ad584f8c8..4d3e94f786 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateBounds.java
+++ b/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 {
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateRegion.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateRegion.java
index a70bb05a41..65b30746f0 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateRegion.java
+++ b/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;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateSpan.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateSpan.java
index 79361f725a..097e88a765 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/CoordinateSpan.java
+++ b/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 {
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ILatLng.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ILatLng.java
index 892d0ad4ae..afd22e5ddb 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ILatLng.java
+++ b/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();
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/IProjectedMeters.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/IProjectedMeters.java
index 5aa5f607eb..43fe25f8e5 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/IProjectedMeters.java
+++ b/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();
 
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
index f1d05542d6..876a12720a 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLng.java
@@ -10,9 +10,10 @@ import com.mapbox.mapboxsdk.constants.MathConstants;
 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>
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngZoom.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngZoom.java
index 9e453a391c..349c098988 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngZoom.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngZoom.java
@@ -5,6 +5,9 @@ import android.os.Parcelable;
 
 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>() {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
index fc821e887c..61a03ff154 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java
@@ -6,10 +6,12 @@ import android.os.Parcelable;
 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 {
 
-- 
cgit v1.2.1