[android] javadoc - inter-link style properties properly

5 files changed, 110 insertions, 20 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
index d7a9282371..55a9799cb7 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonOptions.java
@@ -3,13 +3,17 @@ package com.mapbox.mapboxsdk.style.sources;
 import java.util.HashMap;
 
 /**
- * Options for the <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">GeoJsonSource</a>
+ * Options for the {@link GeoJsonSource}
+ *
+ * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">The online documentation</a>
  */
 public class GeoJsonOptions extends HashMap<String, Object> {
 
     /**
-     * Defaults to 18.
      * Maximum zoom level at which to create vector tiles (higher means greater detail at high zoom levels).
+     *
+     * @param maxZoom the maximum zoom - Defaults to 18.
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withMaxZoom(int maxZoom) {
         this.put("maxzoom", maxZoom);
@@ -17,8 +21,10 @@ public class GeoJsonOptions extends HashMap<String, Object> {
     }
 
     /**
-     * Defaults to 128.
      * Tile buffer size on each side (measured in 1/512ths of a tile; higher means fewer rendering artifacts near tile edges but slower performance).
+     *
+     * @param buffer the buffer size - Defaults to 128.
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withBuffer(int buffer) {
         this.put("buffer", buffer);
@@ -26,8 +32,10 @@ public class GeoJsonOptions extends HashMap<String, Object> {
     }
 
     /**
-     * Defaults to 0.375.
      * Douglas-Peucker simplification tolerance (higher means simpler geometries and faster performance).
+     *
+     * @param tolerance the tolerance - Defaults to 0.375
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withTolerance(float tolerance) {
         this.put("tolerance", tolerance);
@@ -35,8 +43,10 @@ public class GeoJsonOptions extends HashMap<String, Object> {
     }
 
     /**
-     * Defaults to false.
      * If the data is a collection of point features, setting this to true clusters the points by radius into groups.
+     *
+     * @param cluster cluster? - Defaults to false
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withCluster(boolean cluster) {
         this.put("cluster", cluster);
@@ -44,8 +54,10 @@ public class GeoJsonOptions extends HashMap<String, Object> {
     }
 
     /**
-     * Defaults to 50.
-     * Radius of each cluster when clustering points, measured in 1/512ths of a tile.
+     * Max zoom to cluster points on.
+     *
+     * @param clusterMaxZoom clusterMaxZoom cluster maximum zoom - Defaults to one zoom less than maxzoom (so that last zoom features are not clustered)
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withClusterMaxZoom(int clusterMaxZoom) {
         this.put("clusterMaxZoom", clusterMaxZoom);
@@ -53,7 +65,10 @@ public class GeoJsonOptions extends HashMap<String, Object> {
     }
 
     /**
-     * Max zoom to cluster points on. Defaults to one zoom less than maxzoom (so that last zoom features are not clustered).
+     * Radius of each cluster when clustering points, measured in 1/512ths of a tile.
+     *
+     * @param clusterRadius cluster radius - Defaults to 50
+     * @return the current instance for chaining
      */
     public GeoJsonOptions withClusterRadius(int clusterRadius) {
         this.put("clusterRadius", clusterRadius);
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
index a66e0a4adc..80730d143c 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
@@ -8,7 +8,7 @@ import java.util.ArrayList;
 import java.util.HashMap;
 
 /**
- * A GeoJson source.
+ * A GeoJson source. Exposes a {@link FeatureCollection} from Json.
  *
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-geojson">the style specification</a>
  */
@@ -16,6 +16,8 @@ public class GeoJsonSource extends Source {
 
     /**
      * Internal use
+     *
+     * @param nativePtr - pointer to native peer
      */
     public GeoJsonSource(long nativePtr) {
         super(nativePtr);
@@ -32,7 +34,7 @@ public class GeoJsonSource extends Source {
     }
 
     /**
-     * Create an empty GeoJsonSource
+     * Create an empty GeoJsonSource with non-default {@link GeoJsonOptions}
      *
      * @param id      the source id
      * @param options options
@@ -46,7 +48,7 @@ public class GeoJsonSource extends Source {
      * Create a GeoJsonSource from a raw json string
      *
      * @param id      the source id
-     * @param geoJson raw Json body
+     * @param geoJson raw Json FeatureCollection
      */
     public GeoJsonSource(String id, String geoJson) {
         if (geoJson == null || geoJson.startsWith("http")) {
@@ -57,7 +59,7 @@ public class GeoJsonSource extends Source {
     }
 
     /**
-     * Create a GeoJsonSource from a raw json string
+     * Create a GeoJsonSource from a raw json string and non-default {@link GeoJsonOptions}
      *
      * @param id      the source id
      * @param geoJson raw Json body
@@ -83,7 +85,7 @@ public class GeoJsonSource extends Source {
     }
 
     /**
-     * Create a GeoJsonSource from a remote geo json file
+     * Create a GeoJsonSource from a remote geo json file and non-default {@link GeoJsonOptions}
      *
      * @param id      the source id
      * @param url     remote json file
@@ -95,7 +97,7 @@ public class GeoJsonSource extends Source {
     }
 
     /**
-     * Create a GeoJsonSource from a FeatureCollection
+     * Create a GeoJsonSource from a {@link FeatureCollection}
      *
      * @param id       the source id
      * @param features the features
@@ -106,7 +108,7 @@ public class GeoJsonSource extends Source {
     }
 
     /**
-     * Create a GeoJsonSource from a FeatureCollection
+     * Create a GeoJsonSource from a {@link FeatureCollection} and non-default {@link GeoJsonOptions}
      *
      * @param id       the source id
      * @param features the features
@@ -117,21 +119,41 @@ public class GeoJsonSource extends Source {
         setGeoJson(features);
     }
 
+    /**
+     * Updates the GeoJson
+     *
+     * @param features the GeoJSON {@link FeatureCollection}
+     */
     public void setGeoJson(FeatureCollection features) {
         checkValidity();
         setGeoJson(features.toJson());
     }
 
+    /**
+     * Updates the GeoJson
+     *
+     * @param json the raw GeoJson FeatureCollection string
+     */
     public void setGeoJson(String json) {
         checkValidity();
         setRawJson(json);
     }
 
+    /**
+     * Updates the url
+     *
+     * @param url the GeoJSON FeatureCollection url
+     */
     public void setUrl(URL url) {
         checkValidity();
         setUrl(url.toExternalForm());
     }
 
+    /**
+     * Updates the url
+     *
+     * @param url the GeoJSON FeatureCollection url
+     */
     public void setUrl(String url) {
         checkValidity();
         nativeSetUrl(url);
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
index 14bd8bb9ed..7a7ae49909 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/RasterSource.java
@@ -3,36 +3,71 @@ package com.mapbox.mapboxsdk.style.sources;
 import java.net.URL;
 
 /**
- * Construct a Raster Source.
+ * Raster Source enables the use of raster tiles.
  *
- * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The style specificition</a>
+ * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-raster">The style specification</a>
  */
 public class RasterSource extends Source {
     public static final int DEFAULT_TILE_SIZE = 512;
 
     /**
      * Internal use
+     *
+     * @param nativePtr - pointer to native peer
      */
     public RasterSource(long nativePtr) {
         super(nativePtr);
     }
 
+    /**
+     * Create the raster source from an URL
+     *
+     * @param id  the source id
+     * @param url the source url
+     */
     public RasterSource(String id, URL url) {
         this(id, url.toExternalForm());
     }
 
+
+    /**
+     * Create the raster source from an URL
+     *
+     * @param id  the source id
+     * @param url the source url
+     */
     public RasterSource(String id, String url) {
         initialize(id, url, DEFAULT_TILE_SIZE);
     }
 
+    /**
+     * Create the raster source from an URL with a specific tile size
+     *
+     * @param id       the source id
+     * @param url      the source url
+     * @param tileSize the tile size
+     */
     public RasterSource(String id, String url, int tileSize) {
         initialize(id, url, tileSize);
     }
 
+    /**
+     * Create the raster source from a {@link TileSet}
+     *
+     * @param id      the source id
+     * @param tileSet the {@link TileSet}
+     */
     public RasterSource(String id, TileSet tileSet) {
         initialize(id, tileSet.toValueObject(), DEFAULT_TILE_SIZE);
     }
 
+    /**
+     * Create the raster source from a {@link TileSet} with a specific tile size
+     *
+     * @param id       the source id
+     * @param tileSet  the {@link TileSet}
+     * @param tileSize tje tile size
+     */
     public RasterSource(String id, TileSet tileSet, int tileSize) {
         initialize(id, tileSet.toValueObject(), tileSize);
     }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/Source.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/Source.java
index 58ffa12e35..0856b117dc 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/Source.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/Source.java
@@ -1,7 +1,5 @@
 package com.mapbox.mapboxsdk.style.sources;
 
-import java.util.HashMap;
-
 /**
  * Base Peer class for sources. see source.hpp for the other half of the peer.
  */
@@ -9,6 +7,11 @@ public abstract class Source {
     private long nativePtr;
     private boolean invalidated;
 
+    /**
+     * Internal use
+     *
+     * @param nativePtr - pointer to native peer
+     */
     public Source(long nativePtr) {
         this.nativePtr = nativePtr;
     }
@@ -16,11 +19,21 @@ public abstract class Source {
     public Source() {
     }
 
+    /**
+     * Retrieve the source id
+     *
+     * @return the source id
+     */
     public String getId() {
         checkValidity();
         return nativeGetId();
     }
 
+    /**
+     * Internal use
+     *
+     * @return the native peer pointer
+     */
     public long getNativePtr() {
         return nativePtr;
     }
@@ -33,6 +46,9 @@ public abstract class Source {
         }
     }
 
+    /**
+     * Internal use - invalidates the source for further use (after adding it to the map)
+     */
     public final void invalidate() {
         this.invalidated = true;
     }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
index a9c191f96a..689ea7c6bc 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/VectorSource.java
@@ -3,7 +3,7 @@ package com.mapbox.mapboxsdk.style.sources;
 import java.net.URL;
 
 /**
- * A vector source.
+ * Vector source enables the use of vector tiles.
  *
  * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#sources-vector">the style specification</a>
  */
@@ -11,6 +11,8 @@ public class VectorSource extends Source {
 
     /**
      * Internal use
+     *
+     * @param nativePtr - pointer to native peer
      */
     public VectorSource(long nativePtr) {
         super(nativePtr);