[android] Tidy up latest MapView changes. Fix JavaDoc warnings. Imple…

…ment overview and packge-info files.

For mapbox#2002

android/java/.gitignore

@@ -25,3 +25,6 @@ MapboxGLAndroidSDKTestApp/src/main/res/raw/token.txt
 
 # Twitter Fabric / Crashlytics
 fabric.properties
+
+# Capture files
+captures/

android/java/MapboxGLAndroidSDK/build.gradle

@@ -79,13 +79,16 @@ android.libraryVariants.all { variant ->
         destinationDir = new File(destinationDir, variant.baseName)
         source = files(variant.javaCompile.source)
         classpath = files(variant.javaCompile.classpath.files) + files(android.bootClasspath)
-        options.windowTitle("Mapbox Android SDK")
-        options.docTitle("Mapbox Android SDK")
-        options.header("<b>Mapbox Android SDK</b>")
+        //exclude '**/R.java'
+        options.windowTitle("Mapbox Android SDK $VERSION_NAME Reference")
+        options.docTitle("Mapbox Android SDK $VERSION_NAME")
+        options.header("Mapbox Android SDK $VERSION_NAME Reference")
         options.bottom("&copy; 2015 Mapbox. All rights reserved.")
         options.links("http://docs.oracle.com/javase/7/docs/api/")
-        // TODO this will fail as package-list file not online, need to use offline
-        options.links("http://d.android.com/reference/")
+        options.linksOffline("http://d.android.com/reference/", "$System.env.ANDROID_HOME/docs/reference")
+        options.overview("src/main/java/overview.html")
+        options.group("Mapbox Android SDK", "com.mapbox.*")
+        options.group("Third Party Libraries", "com.almeros.*")
         // TODO exclude generated R, BuildConfig, com.almeros.*
     }
 }

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

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

android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polygon.java

@@ -80,7 +80,6 @@ public void setStrokeColor(int color) {
     /**
      * UNIMPLEMENTED: Needs implementation in Native.
      * https://github.com/mapbox/mapbox-gl-native/issues/1737
-     * @return stroke width as float
      */
     public void setStrokeWidth(float width) {
         strokeWidth = width;

android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Polyline.java

@@ -34,7 +34,6 @@ public void setColor(int color) {
      * Sets the width of the polyline.
      *
      * @param width in pixels
-     * @return
      */
     public void setWidth(float width) {
         this.width = width;

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

@@ -58,7 +58,7 @@ public PolylineOptions visible(boolean visible) {
      * Sets the width of the polyline.
      *
      * @param width in pixels
-     * @return
+     * @return a new PolylineOptions
      */
     public PolylineOptions width(float width) {
         ((Polyline)annotation).width = width;

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

@@ -0,0 +1,4 @@
+/**
+ * This package contains classes to add and manage annotations and markers in your map.
+ */
+package com.mapbox.mapboxsdk.annotations;

android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java

@@ -2,11 +2,22 @@
 
 import android.support.annotation.StringDef;
 
+import com.mapbox.mapboxsdk.views.MapView;
+
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
-
+/**
+* Style provides URLs to several professional styles designed by Mapbox.
+* <p/>
+* These styles are all ready to go in your app. To load one, pass it into {@link MapView#setStyleUrl(String)}
+*
+* @see MapView#setStyleUrl(String)
+*/
 public class Style {
 
+    /**
+     * Indicates the parameter accepts one of the values from {@link Style}.
+     */
     @StringDef({MAPBOX_STREETS, EMERALD, LIGHT, DARK, SATELLITE})
     @Retention(RetentionPolicy.SOURCE)
     public @interface StyleUrl {

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

@@ -0,0 +1,4 @@
+/**
+ * This package provides access to several map related constants and bundled styles.
+ */
+package com.mapbox.mapboxsdk.constants;

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

@@ -0,0 +1,4 @@
+/**
+ * This package contains exceptions thrown in this SDK.
+ */
+package com.mapbox.mapboxsdk.exceptions;

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

@@ -0,0 +1,5 @@
+/**
+ * This package contains classes that deal with geometry and map coordinates. Many SDK functions
+ * accept or return these classes.
+ */
+package com.mapbox.mapboxsdk.geometry;

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

@@ -0,0 +1,4 @@
+/**
+ * Do not use this package. Used internally by the SDK.
+ */
+package com.mapbox.mapboxsdk.http;

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

@@ -0,0 +1,5 @@
+/**
+ * This package contains the {@link com.mapbox.mapboxsdk.MapFragment} class. {@code MapFragment}
+ * provides a quick and easy way to add a map to your app.
+ */
+package com.mapbox.mapboxsdk;

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

@@ -0,0 +1,5 @@
+/**
+ * This package contains the {@link com.mapbox.mapboxsdk.utils.ApiAccess} class. {@code ApiAccess}
+ * provides a methods to load a Mapbox access token.
+ */
+package com.mapbox.mapboxsdk.utils;

android/java/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/views/MapView.java

@@ -1297,7 +1297,7 @@ private boolean isFullyLoaded() {
      * <p/>
      * {@code url} can take the following forms:
      * <ul>
-     * <li>{@code MapView.StyleUrls.*}: load one of the bundled styles in {@link Style}.</li>
+     * <li>{@code Style.*}: load one of the bundled styles in {@link Style}.</li>
      * <li>{@code mapbox://styles/<user>/<style>}:
      * retrieves the style from a <a href="https://www.mapbox.com/account/">Mapbox account.</a>
      * {@code user} is your username. {@code style} is the ID of your custom
@@ -1328,9 +1328,20 @@ public void setStyleUrl(@Nullable String url) {
         mNativeMapView.setStyleUrl(url);
     }
 
+    /**
+     * Loads a new map style from the specified bundled style.
+     * <p/>
+     * This method is asynchronous and will return immediately before the style finishes loading.
+     * If you wish to wait for the map to finish loading listen for the {@link MapView#DID_FINISH_LOADING_MAP} event.
+     * <p/>
+     * If the style fails to load or an invalid style URL is set, the map view will become blank.
+     * An error message will be logged in the Android logcat and {@link MapView#DID_FAIL_LOADING_MAP} event will be sent.
+     *
+     * @param style The bundled style. Accepts one of the values from {@link Style}.
+     */
     @UiThread
     @NonNull
-    public void setStyle(@Style.StyleUrl String style){
+    public void setStyle(@Style.StyleUrl String style) {
         setStyleUrl(style);
     }
 
@@ -1854,6 +1865,7 @@ private List<Marker> getMarkersInBounds(@NonNull BoundingBox bbox) {
     /**
      * Get Top Offset for the annotation symbol.
      * Used by InfoWindow
+     *
      * @param symbolName Annotation Symbol
      * @return Top Offset in pixels
      */
@@ -1877,6 +1889,7 @@ public double getMetersPerPixelAtLatitude(@FloatRange(from = -180, to = 180) dou
 
     /**
      * Get ScreenDensity of device
+     *
      * @return Screen Density ratio
      */
     public float getScreenDensity() {

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

@@ -0,0 +1,5 @@
+/**
+ * This package contains the {@link com.mapbox.mapboxsdk.views.MapView} and related classes.
+ * {@code MapView} is the core component of this SDK and adds a map to your app.
+ */
+package com.mapbox.mapboxsdk.views;

android/java/MapboxGLAndroidSDK/src/main/java/overview.html

@@ -0,0 +1,16 @@
+<html>
+<body>
+An open source OpenGL-based vector map solution for Android with full styling capabilities.
+<p/>
+For more information, check out <a href="https://www.mapbox.com/android-sdk/">our online overview</a>.
+<p/>
+<img src="https://raw.githubusercontent.com/mapbox/mapbox-gl-native/master/ios/screenshot.png"/>
+<h2>Changelog</h2>
+<h3>2.1.0</h3>
+Initial release.
+<h3>2.0.0</h3>
+Initial preview release.
+<h3>0.1.0</h3>
+<p>Initial beta release.</p>
+</body>
+</html>