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 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 * - * @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) {