From b032296703a14234de143251d5560e159cc83517 Mon Sep 17 00:00:00 2001
From: Tobrun Van Nuland
Date: Thu, 16 Mar 2017 13:17:54 +0100
Subject: [PATCH 1/3] [android] - update javadoc 5.0.0 release
---
.../main/java/com/mapbox/mapboxsdk/storage/package-info.java | 4 ++++
1 file changed, 4 insertions(+)
create mode 100644 platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java
new file mode 100644
index 00000000000..85950735ef7
--- /dev/null
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/package-info.java
@@ -0,0 +1,4 @@
+/**
+ * Contains the Mapbox Maps Android Storage API classes.
+ */
+package com.mapbox.mapboxsdk.storage;
From a72318bb11cc2f0c44f86661906fdeee149acacd Mon Sep 17 00:00:00 2001
From: Tobrun Van Nuland
Date: Thu, 16 Mar 2017 13:18:27 +0100
Subject: [PATCH 2/3] update annotation and sources package javadoc
---
.../mapboxsdk/annotations/Annotation.java | 22 ++++++++++++-------
.../exceptions/ConversionException.java | 13 +----------
.../InvalidMarkerPositionException.java | 3 +++
.../style/sources/GeoJsonOptions.java | 3 ++-
.../style/sources/GeoJsonSource.java | 2 +-
.../mapboxsdk/style/sources/RasterSource.java | 2 +-
.../mapboxsdk/style/sources/TileSet.java | 2 +-
.../mapboxsdk/style/sources/VectorSource.java | 2 +-
8 files changed, 24 insertions(+), 25 deletions(-)
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 831c1db5a31..a588ff6d234 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
@@ -6,10 +6,12 @@
import com.mapbox.mapboxsdk.maps.MapboxMap;
/**
- * Annotation is an overlay on top of a {@link MapView},
- * from which {@link Polygon}, {@link Polyline} and {@link Marker} are derived.
+ * Annotation is an overlay on top of a Map.
*
- * it manages attachment to a map and identification, but does not require
+ * Known subclasses are {@link Polygon}, {@link Polyline} and {@link Marker}.
+ *
+ *
+ * This class manages attachment to a map and identification, but does not require
* content to be placed at a geographical point.
*
*/
@@ -96,6 +98,12 @@ protected MapView getMapView() {
return mapView;
}
+ /**
+ * Compares this Annotation object with another Annotation.
+ *
+ * @param annotation Another Annotation to compare with this object.
+ * @return returns 0 if id's match, 1 if id is lower, -1 if id is higher of another Annotation
+ */
@Override
public int compareTo(@NonNull Annotation annotation) {
if (id < annotation.getId()) {
@@ -107,12 +115,10 @@ public int compareTo(@NonNull Annotation annotation) {
}
/**
- * Compares this {@link PolylineOptions} object with another {@link PolylineOptions} and
- * determines if their color, alpha, width, and vertices match.
+ * Checks if this Annotation object is equal to another Annotation.
*
- * @param object Another {@link PolylineOptions} to compare with this object.
- * @return True if color, alpha, width, and vertices match this {@link PolylineOptions} object.
- * Else, false.
+ * @param object Another Annotation to check equality with this object.
+ * @return returns true both id's match else returns false.
*/
@Override
public boolean equals(Object object) {
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
index be2b586683e..0d16c53b868 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/ConversionException.java
@@ -1,22 +1,11 @@
package com.mapbox.mapboxsdk.exceptions;
/**
- * Thrown on conversion errors
+ * A ConversionException is thrown when a conversion failed to execute.
*/
public class ConversionException extends RuntimeException {
- public ConversionException() {
- }
-
public ConversionException(String detailMessage) {
super(detailMessage);
}
-
- public ConversionException(String detailMessage, Throwable throwable) {
- super(detailMessage, throwable);
- }
-
- public ConversionException(Throwable throwable) {
- super(throwable);
- }
}
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
index bd24379af36..f0f9b9236b2 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidMarkerPositionException.java
@@ -1,5 +1,8 @@
package com.mapbox.mapboxsdk.exceptions;
+/**
+ * A InvalidMarkerPositionException is thrown when a Marker object is created with an invalid LatLng position.
+ */
public class InvalidMarkerPositionException extends RuntimeException {
public InvalidMarkerPositionException() {
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 27a3d5c8987..1a1711e547b 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,8 +3,9 @@
import java.util.HashMap;
/**
- * Options for the {@link GeoJsonSource}
+ * Builder class for composing GeoJsonSource objects.
*
+ * @see GeoJsonSource
* @see The online documentation
*/
public class GeoJsonOptions extends HashMap {
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 9f957e7727c..b2535957131 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
@@ -15,7 +15,7 @@
import java.util.List;
/**
- * A GeoJson source. Exposes a {@link FeatureCollection} from Json.
+ * GeoJson source, allows using FeatureCollections from Json.
*
* @see the style specification
*/
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 eabbdb83951..98b74afcffb 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,7 +3,7 @@
import java.net.URL;
/**
- * Raster Source enables the use of raster tiles.
+ * Raster source, allows using raster tiles as source.
*
* @see The style specification
*/
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
index 9f403c2fb9c..54e4e5f5d3f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/TileSet.java
@@ -8,7 +8,7 @@
import java.util.Map;
/**
- * Tile set
+ * Tile set, allows using TileJson specification as source.
*
* @see The tileset specification
*/
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 68eb81b7f46..cff5ab63531 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
@@ -14,7 +14,7 @@
import java.util.List;
/**
- * Vector source enables the use of vector tiles.
+ * Vector source, allows the use of vector tiles.
*
* @see the style specification
*/
From f290c24c40429b6d2727c46448808b910f93fe5e Mon Sep 17 00:00:00 2001
From: Tobrun Van Nuland
Date: Thu, 16 Mar 2017 13:40:23 +0100
Subject: [PATCH 3/3] update javadoc on MapboxMap and MapView
---
.../com/mapbox/mapboxsdk/maps/MapView.java | 2 +-
.../com/mapbox/mapboxsdk/maps/MapboxMap.java | 95 +++++++++++++------
2 files changed, 69 insertions(+), 28 deletions(-)
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
index a2b6fb1f42e..c6fd7ff58e8 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java
@@ -803,7 +803,7 @@ public void onClick(DialogInterface dialog, int which) {
public static final int DID_FINISH_RENDERING_FRAME = 9;
/**
- * This event is triggered when the map finished rendeirng the frame fully.
+ * This event is triggered when the map finished rendering the frame fully.
*
* Register to {@link MapChange} events with {@link MapView#addOnMapChangedListener(OnMapChangedListener)}.
*
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
index 5d2c649d325..6edae8b9447 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java
@@ -96,6 +96,9 @@ void initialise(@NonNull Context context, @NonNull MapboxMapOptions options) {
setStyleUrl(options);
}
+ /**
+ * Called when the hosting Activity/Fragment onStart() method is called.
+ */
void onStart() {
nativeMapView.update();
trackingSettings.onStart();
@@ -105,10 +108,18 @@ void onStart() {
}
}
+ /**
+ * Called when the hosting Activity/Fragment onStop() method is called.
+ */
void onStop() {
trackingSettings.onStop();
}
+ /**
+ * Called when the hosting Activity/Fragment is going to be destroyed and map state needs to be saved.
+ *
+ * @param outState the bundle to save the state to.
+ */
void onSaveInstanceState(Bundle outState) {
outState.putParcelable(MapboxConstants.STATE_CAMERA_POSITION, transform.getCameraPosition());
outState.putBoolean(MapboxConstants.STATE_DEBUG_ACTIVE, nativeMapView.getDebug());
@@ -117,6 +128,11 @@ void onSaveInstanceState(Bundle outState) {
uiSettings.onSaveInstanceState(outState);
}
+ /**
+ * Called when the hosting Activity/Fragment is recreated and map state needs to be restored.
+ *
+ * @param savedInstanceState the bundle containing the saved state
+ */
void onRestoreInstanceState(Bundle savedInstanceState) {
final CameraPosition cameraPosition = savedInstanceState.getParcelable(MapboxConstants.STATE_CAMERA_POSITION);
if (cameraPosition != null) {
@@ -153,13 +169,16 @@ void onPostMapReady() {
}
/**
- * Called when the user
+ * Called when the region is changing or has changed.
*/
void onUpdateRegionChange() {
trackingSettings.update();
annotationManager.update();
}
+ /**
+ * Called when the map frame is fully rendered.
+ */
void onUpdateFullyRendered() {
CameraPosition cameraPosition = transform.invalidateCameraPosition();
if (cameraPosition != null) {
@@ -819,10 +838,20 @@ public void setFocalBearing(double bearing, float focalX, float focalY, long dur
transform.setBearing(bearing, focalX, focalY, duration);
}
+ /**
+ * Returns the measured height of the Map.
+ *
+ * @return the height of the map
+ */
public float getHeight() {
return nativeMapView.getHeight();
}
+ /**
+ * Returns the measured width of the Map.
+ *
+ * @return the width of the map
+ */
public float getWidth() {
return nativeMapView.getWidth();
}
@@ -1014,7 +1043,7 @@ private void setStyleUrl(@NonNull MapboxMapOptions options) {
/**
* Returns the map style currently displayed in the map view.
*
- * @return The URL of the map style.
+ * @return The URL of the map style
*/
@UiThread
@Nullable
@@ -1033,8 +1062,8 @@ public String getStyleUrl() {
* The marker's icon is rendered on the map at the location {@code Marker.position}.
* If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
*
- * @param markerOptions A marker options object that defines how to render the marker.
- * @return The {@code Marker} that was added to the map.
+ * @param markerOptions A marker options object that defines how to render the marker
+ * @return The {@code Marker} that was added to the map
*/
@UiThread
@NonNull
@@ -1049,8 +1078,8 @@ public Marker addMarker(@NonNull MarkerOptions markerOptions) {
* The marker's icon is rendered on the map at the location {@code Marker.position}.
* If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
*
- * @param markerOptions A marker options object that defines how to render the marker.
- * @return The {@code Marker} that was added to the map.
+ * @param markerOptions A marker options object that defines how to render the marker
+ * @return The {@code Marker} that was added to the map
*/
@UiThread
@NonNull
@@ -1065,8 +1094,8 @@ public Marker addMarker(@NonNull BaseMarkerOptions markerOptions) {
* The marker's icon is rendered on the map at the location {@code Marker.position}.
* If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
*
- * @param markerOptions A marker options object that defines how to render the marker.
- * @return The {@code Marker} that was added to the map.
+ * @param markerOptions A marker options object that defines how to render the marker
+ * @return The {@code Marker} that was added to the map
*/
@UiThread
@NonNull
@@ -1074,7 +1103,6 @@ public MarkerView addMarker(@NonNull BaseMarkerViewOptions markerOptions) {
return annotationManager.addMarker(markerOptions, this, null);
}
-
/**
*
* Adds a marker to this map.
@@ -1082,9 +1110,9 @@ public MarkerView addMarker(@NonNull BaseMarkerViewOptions markerOptions) {
* The marker's icon is rendered on the map at the location {@code Marker.position}.
* If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
*
- * @param markerOptions A marker options object that defines how to render the marker.
- * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map.
- * @return The {@code Marker} that was added to the map.
+ * @param markerOptions A marker options object that defines how to render the marker
+ * @param onMarkerViewAddedListener Callback invoked when the View has been added to the map
+ * @return The {@code Marker} that was added to the map
*/
@UiThread
@NonNull
@@ -1094,7 +1122,14 @@ public MarkerView addMarker(@NonNull BaseMarkerViewOptions markerOptions,
}
/**
- * FIXME javadoc
+ * Adds multiple markersViews to this map.
+ *
+ * The marker's icon is rendered on the map at the location {@code Marker.position}.
+ * If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
+ *
+ *
+ * @param markerViewOptions A list of markerView options objects that defines how to render the markers
+ * @return A list of the {@code MarkerView}s that were added to the map
*/
@UiThread
@NonNull
@@ -1104,7 +1139,10 @@ public List addMarkerViews(@NonNull List extends
}
/**
- * FIXME javadoc
+ * Returns markerViews found inside of a rectangle on this map.
+ *
+ * @param rect the rectangular area on the map to query for markerViews
+ * @return A list of the markerViews that were found in the rectangle
*/
@UiThread
@NonNull
@@ -1119,8 +1157,8 @@ public List getMarkerViewsInRect(@NonNull RectF rect) {
* The marker's icon is rendered on the map at the location {@code Marker.position}.
* If {@code Marker.title} is defined, the map shows an info box with the marker's title and snippet.
*
- * @param markerOptionsList A list of marker options objects that defines how to render the markers.
- * @return A list of the {@code Marker}s that were added to the map.
+ * @param markerOptionsList A list of marker options objects that defines how to render the markers
+ * @return A list of the {@code Marker}s that were added to the map
*/
@UiThread
@NonNull
@@ -1134,7 +1172,7 @@ public List addMarkers(@NonNull List extends
* Updates a marker on this map. Does nothing if the marker isn't already added.
*
*
- * @param updatedMarker An updated marker object.
+ * @param updatedMarker An updated marker object
*/
@UiThread
public void updateMarker(@NonNull Marker updatedMarker) {
@@ -1144,8 +1182,8 @@ public void updateMarker(@NonNull Marker updatedMarker) {
/**
* Adds a polyline to this map.
*
- * @param polylineOptions A polyline options object that defines how to render the polyline.
- * @return The {@code Polyine} that was added to the map.
+ * @param polylineOptions A polyline options object that defines how to render the polyline
+ * @return The {@code Polyine} that was added to the map
*/
@UiThread
@NonNull
@@ -1190,8 +1228,8 @@ public Polygon addPolygon(@NonNull PolygonOptions polygonOptions) {
/**
* Adds multiple polygons to this map.
*
- * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons.
- * @return A list of the {@code Polygon}s that were added to the map.
+ * @param polygonOptionsList A list of polygon options objects that defines how to render the polygons
+ * @return A list of the {@code Polygon}s that were added to the map
*/
@UiThread
@NonNull
@@ -1199,11 +1237,10 @@ public List addPolygons(@NonNull List polygonOptionsLis
return annotationManager.addPolygons(polygonOptionsList, this);
}
-
/**
* Update a polygon on this map.
*
- * @param polygon An updated polygon object.
+ * @param polygon An updated polygon object
*/
@UiThread
public void updatePolygon(Polygon polygon) {
@@ -1214,7 +1251,7 @@ public void updatePolygon(Polygon polygon) {
*
* Convenience method for removing a Marker from the map.
*
- * Calls removeAnnotation() internally
+ * Calls removeAnnotation() internally.
*
* @param marker Marker to remove
*/
@@ -1227,7 +1264,7 @@ public void removeMarker(@NonNull Marker marker) {
*
* Convenience method for removing a Polyline from the map.
*
- * Calls removeAnnotation() internally
+ * Calls removeAnnotation() internally.
*
* @param polyline Polyline to remove
*/
@@ -1240,7 +1277,7 @@ public void removePolyline(@NonNull Polyline polyline) {
*
* Convenience method for removing a Polygon from the map.
*
- * Calls removeAnnotation() internally
+ * Calls removeAnnotation() internally.
*
* @param polygon Polygon to remove
*/
@@ -1620,6 +1657,11 @@ public OnInfoWindowLongClickListener getOnInfoWindowLongClickListener() {
return annotationManager.getInfoWindowManager().getOnInfoWindowLongClickListener();
}
+ /**
+ * Set an callback to be invoked when an InfoWindow closes.
+ *
+ * @param listener callback invoked when an InfoWindow closes
+ */
public void setOnInfoWindowCloseListener(@Nullable OnInfoWindowCloseListener listener) {
annotationManager.getInfoWindowManager().setOnInfoWindowCloseListener(listener);
}
@@ -1719,7 +1761,6 @@ public void setOnMyBearingTrackingModeChangeListener(@Nullable OnMyBearingTracki
* Takes a snapshot of the map.
*
* @param callback Callback method invoked when the snapshot is taken.
- * @param bitmap A pre-allocated bitmap.
*/
@UiThread
public void snapshot(@NonNull SnapshotReadyCallback callback) {