From a9f52e24e63af6d322b3f4744a38aab395344b1d Mon Sep 17 00:00:00 2001 From: Tobrun Date: Tue, 20 Jun 2017 15:48:24 +0200 Subject: [PATCH] Revisit Javadoc for 5.1.0 (#9266) * [android] - revisit public API javadoc * [android] fix javadoc minor mistakes and typos * grammar tweak * add missing public javadoc --- .../java/com/mapbox/mapboxsdk/Mapbox.java | 7 +- .../mapboxsdk/annotations/BubbleLayout.java | 106 +++++++++++++ .../mapboxsdk/annotations/IconFactory.java | 46 +++--- .../annotations/MarkerViewManager.java | 19 ++- .../mapboxsdk/camera/CameraPosition.java | 60 +++---- .../mapbox/mapboxsdk/camera/CameraUpdate.java | 8 +- .../mapboxsdk/camera/CameraUpdateFactory.java | 4 +- .../constants/MyBearingTracking.java | 14 +- .../constants/MyLocationTracking.java | 19 ++- .../com/mapbox/mapboxsdk/constants/Style.java | 1 - .../IconBitmapChangedException.java | 6 +- .../InvalidLatLngBoundsException.java | 4 +- .../InvalidMarkerPositionException.java | 3 + .../MapboxConfigurationException.java | 4 + .../exceptions/TooManyIconsException.java | 5 +- .../mapbox/mapboxsdk/geometry/ILatLng.java | 18 ++- .../mapboxsdk/geometry/IProjectedMeters.java | 12 ++ .../com/mapbox/mapboxsdk/geometry/LatLng.java | 116 ++++++++++++-- .../mapboxsdk/geometry/LatLngBounds.java | 148 +++++++++++------ .../mapbox/mapboxsdk/geometry/LatLngSpan.java | 46 +++++- .../mapboxsdk/geometry/ProjectedMeters.java | 45 +++++- .../mapboxsdk/geometry/VisibleRegion.java | 31 +++- .../mapboxsdk/location/LocationSource.java | 8 +- .../com/mapbox/mapboxsdk/maps/MapView.java | 30 ++-- .../com/mapbox/mapboxsdk/maps/MapboxMap.java | 30 ++-- .../mapboxsdk/maps/MapboxMapOptions.java | 6 +- .../com/mapbox/mapboxsdk/maps/UiSettings.java | 12 +- .../maps/widgets/MyLocationView.java | 150 +++++++++++++++++- .../maps/widgets/MyLocationViewSettings.java | 7 +- .../mapboxsdk/net/ConnectivityReceiver.java | 7 +- .../mapboxsdk/offline/OfflineManager.java | 6 + .../mapboxsdk/offline/OfflineRegion.java | 1 + .../offline/OfflineRegionStatus.java | 60 ++++++- .../mapbox/mapboxsdk/storage/FileSource.java | 19 ++- .../mapboxsdk/style/layers/PropertyValue.java | 30 ++++ .../mapbox/mapboxsdk/style/light/Light.java | 22 ++- .../mapboxsdk/style/light/Position.java | 4 +- .../mapboxsdk/style/light/light.java.ejs | 2 +- .../mapbox/mapboxsdk/utils/BitmapUtils.java | 16 ++ .../mapbox/mapboxsdk/utils/ColorUtils.java | 10 +- .../mapboxsdk/utils/MapFragmentUtils.java | 13 ++ 41 files changed, 940 insertions(+), 215 deletions(-) diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java index 17cd4e0dce5..6722000be7e 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/Mapbox.java @@ -1,6 +1,5 @@ package com.mapbox.mapboxsdk; -import android.app.Application; import android.content.Context; import android.net.ConnectivityManager; import android.net.NetworkInfo; @@ -17,10 +16,10 @@ import com.mapbox.services.android.telemetry.location.LocationEnginePriority; /** - * The entry point of the Mapbox Android SDK. + * The entry point to initialize the Mapbox Android SDK. *

* Obtain a reference by calling {@link #getInstance(Context, String)}. Usually this class is configured in - * {@link Application#onCreate()} and is responsible for the active access token, application context, and + * Application#onCreate() and is responsible for the active access token, application context, and * connectivity state. *

*/ @@ -97,6 +96,8 @@ private static void validateAccessToken() throws MapboxConfigurationException { /** * Application context + * + * @return the application context */ public static Context getApplicationContext() { return INSTANCE.context; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BubbleLayout.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BubbleLayout.java index 07e038c08cf..c58cc310a8e 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BubbleLayout.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/BubbleLayout.java @@ -27,14 +27,32 @@ public class BubbleLayout extends LinearLayout { private float strokeWidth; private int strokeColor; + /** + * Creates an instance of bubble layout. + * + * @param context The context used to inflate this bubble layout + */ public BubbleLayout(Context context) { this(context, null, 0); } + /** + * Creates an instance of bubble layout. + * + * @param context The context used to inflate this bubble layout + * @param attrs The attribute set to initialise this bubble layout from + */ public BubbleLayout(Context context, AttributeSet attrs) { this(context, attrs, 0); } + /** + * Creates an instance of bubble layout. + * + * @param context The context used to inflate this bubble layout + * @param attrs The attribute set to initialise this bubble layout from + * @param defStyleAttr The default style to apply this bubble layout with + */ public BubbleLayout(Context context, AttributeSet attrs, int defStyleAttr) { super(context, attrs, defStyleAttr); @@ -78,10 +96,21 @@ static float convertDpToPixel(float dp, Context context) { return dp * (metrics.densityDpi / DisplayMetrics.DENSITY_DEFAULT); } + /** + * Get the arrow direction. + * + * @return the arrow direction + */ public ArrowDirection getArrowDirection() { return arrowDirection; } + /** + * Set the arrow direction. + * + * @param arrowDirection The direction of the arrow + * @return this + */ public BubbleLayout setArrowDirection(ArrowDirection arrowDirection) { resetPadding(); this.arrowDirection = arrowDirection; @@ -89,10 +118,21 @@ public BubbleLayout setArrowDirection(ArrowDirection arrowDirection) { return this; } + /** + * Get the arrow width. + * + * @return the width of the arrow + */ public float getArrowWidth() { return arrowWidth; } + /** + * Set the arrow width. + * + * @param arrowWidth The width of the arrow + * @return this + */ public BubbleLayout setArrowWidth(float arrowWidth) { resetPadding(); this.arrowWidth = arrowWidth; @@ -100,10 +140,21 @@ public BubbleLayout setArrowWidth(float arrowWidth) { return this; } + /** + * Get the arrow height + * + * @return the height of the arrow + */ public float getArrowHeight() { return arrowHeight; } + /** + * Set the arrow height. + * + * @param arrowHeight The height of the arrow + * @return this + */ public BubbleLayout setArrowHeight(float arrowHeight) { resetPadding(); this.arrowHeight = arrowHeight; @@ -111,10 +162,21 @@ public BubbleLayout setArrowHeight(float arrowHeight) { return this; } + /** + * Get the arrow position. + * + * @return the arrow position + */ public float getArrowPosition() { return arrowPosition; } + /** + * Get the arrow position. + * + * @param arrowPosition The arrow position + * @return this + */ public BubbleLayout setArrowPosition(float arrowPosition) { resetPadding(); this.arrowPosition = arrowPosition; @@ -122,30 +184,63 @@ public BubbleLayout setArrowPosition(float arrowPosition) { return this; } + /** + * Get the corner radius + * + * @return the corner radius + */ public float getCornersRadius() { return cornersRadius; } + /** + * Set the corner radius + * + * @param cornersRadius The corner radius + * @return this + */ public BubbleLayout setCornersRadius(float cornersRadius) { this.cornersRadius = cornersRadius; requestLayout(); return this; } + /** + * Get the bubble color. + * + * @return the bubble color + */ public int getBubbleColor() { return bubbleColor; } + /** + * Set the bubble color. + * + * @param bubbleColor The buble color + * @return this + */ public BubbleLayout setBubbleColor(int bubbleColor) { this.bubbleColor = bubbleColor; requestLayout(); return this; } + /** + * Get stroke width. + * + * @return the stroke width + */ public float getStrokeWidth() { return strokeWidth; } + /** + * Set the stroke width. + * + * @param strokeWidth The stroke width + * @return this + */ public BubbleLayout setStrokeWidth(float strokeWidth) { resetPadding(); this.strokeWidth = strokeWidth; @@ -153,10 +248,21 @@ public BubbleLayout setStrokeWidth(float strokeWidth) { return this; } + /** + * Get the stroke color. + * + * @return the stroke color + */ public int getStrokeColor() { return strokeColor; } + /** + * Set the stroke color. + * + * @param strokeColor The stroke color + * @return this + */ public BubbleLayout setStrokeColor(int strokeColor) { this.strokeColor = strokeColor; requestLayout(); 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 57aa512401b..f9ca9bf4ccf 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 @@ -23,7 +23,7 @@ /** * Factory for creating Icons from bitmap images. *

- * {@link Icon} is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}. + * icon is used to display bitmaps on top of the map using {@link Marker} and {@link MarkerView}. *

* * @see Icon @@ -42,6 +42,12 @@ public final class IconFactory { private int nextId = 0; + /** + * Get a single instance of IconFactory. + * + * @param context the context to derive the application context from + * @return the single instance of IconFactory + */ public static synchronized IconFactory getInstance(@NonNull Context context) { if (instance == null) { instance = new IconFactory(context.getApplicationContext()); @@ -71,10 +77,10 @@ private IconFactory(@NonNull Context context) { } /** - * Creates an {@link Icon} from a given Bitmap image. + * Creates an icon from a given Bitmap image. * * @param bitmap image used for creating the Icon. - * @return The {@link Icon} using the given Bitmap image. + * @return The icon using the given Bitmap image. */ public Icon fromBitmap(@NonNull Bitmap bitmap) { if (nextId < 0) { @@ -85,10 +91,10 @@ public Icon fromBitmap(@NonNull Bitmap bitmap) { } /** - * Create an {@link Icon} using the resource ID of a Bitmap image. + * Creates an icon using the resource ID of a Bitmap image. * * @param resourceId The resource ID of a Bitmap image. - * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + * @return The icon that was loaded from the asset or {@code null} if failed to load. */ public Icon fromResource(@DrawableRes int resourceId) { Drawable drawable = ContextCompat.getDrawable(context, resourceId); @@ -101,9 +107,9 @@ public Icon fromResource(@DrawableRes int resourceId) { } /** - * Provides an {@link Icon} using the default marker icon used for {@link Marker}. + * Provides an icon using the default marker icon used for {@link Marker}. * - * @return An {@link Icon} with the default {@link Marker} icon. + * @return An icon with the default {@link Marker} icon. */ public Icon defaultMarker() { if (defaultMarker == null) { @@ -113,9 +119,9 @@ public Icon defaultMarker() { } /** - * Provides an {@link Icon} using the default marker icon used for {@link MarkerView}. + * Provides an icon using the default marker icon used for {@link MarkerView}. * - * @return An {@link Icon} with the default {@link MarkerView} icon. + * @return An icon with the default {@link MarkerView} icon. */ public Icon defaultMarkerView() { if (defaultMarkerView == null) { @@ -130,10 +136,10 @@ private Icon fromInputStream(@NonNull InputStream is) { } /** - * Creates an {@link Icon} using the name of a Bitmap image in the assets directory. + * Creates an Icon using the name of a Bitmap image in the assets directory. * * @param assetName The name of a Bitmap image in the assets directory. - * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + * @return The Icon that was loaded from the asset or null if failed to load. */ public Icon fromAsset(@NonNull String assetName) { InputStream is; @@ -146,11 +152,10 @@ public Icon fromAsset(@NonNull String assetName) { } /** - * Creates an {@link Icon} using the absolute file path of a Bitmap image. + * Creates an Icon using the absolute file path of a Bitmap image. * * @param absolutePath The absolute path of the Bitmap image. - * @return The {@link Icon} that was loaded from the absolute path or {@code null} if failed to - * load. + * @return The Icon that was loaded from the absolute path or null if failed to load. */ public Icon fromPath(@NonNull String absolutePath) { Bitmap bitmap = BitmapFactory.decodeFile(absolutePath, options); @@ -158,11 +163,11 @@ public Icon fromPath(@NonNull String absolutePath) { } /** - * Create an {@link Icon} using the name of a Bitmap image file located in the internal storage. - * In particular, this calls {@link Context#openFileInput(String)}. + * Create an Icon using the name of a Bitmap image file located in the internal storage. + * In particular, this calls Context#openFileInput(String). * * @param fileName The name of the Bitmap image file. - * @return The {@link Icon} that was loaded from the asset or {@code null} if failed to load. + * @return The Icon that was loaded from the asset or null if failed to load. * @see * Using the Internal Storage */ @@ -177,12 +182,11 @@ public Icon fromFile(@NonNull String fileName) { } /** - * Create an {@link Icon} using a previously created icon identifier along with a provided - * Bitmap. + * Create an Icon using a previously created icon identifier along with a provided Bitmap. * - * @param iconId The {@link Icon} identifier you'd like to recreate. + * @param iconId The Icon identifier you'd like to recreate. * @param bitmap a Bitmap used to replace the current one. - * @return The {@link Icon} using the new Bitmap. + * @return The Icon using the new Bitmap. */ public static Icon recreate(@NonNull String iconId, @NonNull Bitmap bitmap) { return new Icon(iconId, bitmap); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java index b9e9bea4ede..6d42842b7dc 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java @@ -135,6 +135,12 @@ public void animateRotationBy(@NonNull MarkerView marker, float rotation) { } } + /** + * Set the rotation of a MarkerView to a given rotation value. + * + * @param marker The MarkerView to change its rotation value + * @param rotation The rotation value + */ public void setRotation(@NonNull MarkerView marker, float rotation) { View convertView = markerViewMap.get(marker); if (convertView != null) { @@ -544,10 +550,11 @@ public void invalidateViewMarkersInVisibleRegion() { } /** - * When the provided {@link MarkerView} is clicked on by a user, we check if a custom click - * event has been created and if not, display a {@link InfoWindow}. + * When the provided MarkerView is clicked on by a user, we check if a custom click + * event has been created and if not, display a InfoWindow. * - * @param markerView that the click event occurred. + * @param markerView that the click event occurred + * @return true if the marker view click has been handled, false if not */ public boolean onClickMarkerView(MarkerView markerView) { boolean clickHandled = false; @@ -572,9 +579,9 @@ public boolean onClickMarkerView(MarkerView markerView) { } /** - * Handles the {@link MarkerView}'s info window offset. + * Handles the MarkerView info window offset. * - * @param marker that we are ensuring info window offset. + * @param marker that we are ensuring info window offset */ public void ensureInfoWindowOffset(MarkerView marker) { View view = null; @@ -624,7 +631,7 @@ public void addOnMarkerViewAddedListener(MarkerView markerView, OnMarkerViewAdde } /** - * Default MarkerViewAdapter used for base class of {@link MarkerView} to adapt a MarkerView to + * Default MarkerViewAdapter used for base class of MarkerView to adapt a MarkerView to * an ImageView. */ private static class ImageMarkerViewAdapter extends MapboxMap.MarkerViewAdapter { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java index 66c261f1d0b..c2f19072dbd 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java @@ -3,6 +3,7 @@ import android.content.res.TypedArray; import android.os.Parcel; import android.os.Parcelable; +import android.support.annotation.FloatRange; import com.mapbox.mapboxsdk.R; import com.mapbox.mapboxsdk.constants.MapboxConstants; @@ -166,14 +167,14 @@ public static final class Builder { private double zoom = -1; /** - * Creates an empty builder. + * Create an empty builder. */ public Builder() { super(); } /** - * Create Builder with an existing CameraPosition data. + * Create a builder with an existing CameraPosition data. * * @param previous Existing CameraPosition values to use */ @@ -188,7 +189,7 @@ public Builder(CameraPosition previous) { } /** - * Create Builder with an existing CameraPosition data. + * Create a builder with an existing CameraPosition data. * * @param typedArray TypedArray containing attribute values */ @@ -205,7 +206,7 @@ public Builder(TypedArray typedArray) { } /** - * Create Builder from an existing CameraPositionUpdate update. + * Create a builder from an existing CameraPositionUpdate update. * * @param update Update containing camera options */ @@ -220,7 +221,7 @@ public Builder(CameraUpdateFactory.CameraPositionUpdate update) { } /** - * Create Builder from an existing CameraPositionUpdate update. + * Create builder from an existing CameraPositionUpdate update. * * @param update Update containing camera options */ @@ -235,7 +236,7 @@ public Builder(CameraUpdateFactory.ZoomUpdate update) { * Sets the direction that the camera is pointing in, in degrees clockwise from north. * * @param bearing Bearing - * @return Builder + * @return this */ public Builder bearing(double bearing) { double direction = bearing; @@ -252,19 +253,10 @@ public Builder bearing(double bearing) { } /** - * Builds a CameraPosition. + * Sets the location where the camera is pointing at. * - * @return CameraPosition - */ - public CameraPosition build() { - return new CameraPosition(target, zoom, tilt, bearing); - } - - /** - * Sets the location that the camera is pointing at. - * - * @param location Location - * @return Builder + * @param location target of the camera + * @return this */ public Builder target(LatLng location) { this.target = location; @@ -272,28 +264,42 @@ public Builder target(LatLng location) { } /** - * Set the tilt in degrees + * Set the tilt of the camera in degrees *

- * value is clamped to 0 and 60. + * value is clamped to {@link MapboxConstants#MINIMUM_TILT} and {@link MapboxConstants#MAXIMUM_TILT}. *

* - * @param tilt Tilt value - * @return Builder + * @param tilt Tilt value of the camera + * @return this */ - public Builder tilt(double tilt) { + public Builder tilt(@FloatRange(from = MapboxConstants.MINIMUM_TILT, + to = MapboxConstants.MAXIMUM_TILT) double tilt) { this.tilt = MathUtils.clamp(tilt, MapboxConstants.MINIMUM_TILT, MapboxConstants.MAXIMUM_TILT); return this; } /** - * Set the zoom + * Set the zoom of the camera + *

+ * Zoom ranges from {@link MapboxConstants#MINIMUM_ZOOM} to {@link MapboxConstants#MAXIMUM_ZOOM} + *

* - * @param zoom Zoom value - * @return Builder + * @param zoom Zoom value of the camera + * @return this */ - public Builder zoom(double zoom) { + public Builder zoom(@FloatRange(from = MapboxConstants.MINIMUM_ZOOM, + to = MapboxConstants.MAXIMUM_ZOOM) double zoom) { this.zoom = zoom; return this; } + + /** + * Builds the CameraPosition. + * + * @return CameraPosition + */ + public CameraPosition build() { + return new CameraPosition(target, zoom, tilt, bearing); + } } } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java index 498aa8343b7..31f13cbcff7 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdate.java @@ -6,10 +6,16 @@ import com.mapbox.mapboxsdk.maps.MapboxMap; /** - * Interface definition for camera position changes. + * Interface definition for camera updates. */ public interface CameraUpdate { + /** + * Get the camera position from the camera update. + * + * @param mapboxMap Map object to build the position from + * @return the camera position from the implementing camera update + */ @Nullable CameraPosition getCameraPosition(@NonNull MapboxMap mapboxMap); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java index 8e1411e2739..50e33f4f9fe 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraUpdateFactory.java @@ -42,7 +42,7 @@ public static CameraUpdate newLatLng(@NonNull LatLng latLng) { } /** - * Returns a {@link CameraUpdate} that transforms the camera such that the specified + * Returns a CameraUpdate that transforms the camera such that the specified * latitude/longitude bounds are centered on screen at the greatest possible zoom level. * You can specify padding, in order to inset the bounding box from the map view's edges. * The returned CameraUpdate has a bearing of 0 and a tilt of 0. @@ -56,7 +56,7 @@ public static CameraUpdate newLatLngBounds(@NonNull LatLngBounds bounds, int pad } /** - * Returns a {@link CameraUpdate} that transforms the camera such that the specified + * Returns a CameraUpdate that transforms the camera such that the specified * latitude/longitude bounds are centered on screen at the greatest possible zoom level. * You can specify padding, in order to inset the bounding box from the map view's edges. * The returned CameraUpdate has a bearing of 0 and a tilt of 0. diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java index 88c3bef6733..ceac862f39a 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyBearingTracking.java @@ -2,23 +2,27 @@ import android.support.annotation.IntDef; +import com.mapbox.mapboxsdk.maps.MapboxMap; import com.mapbox.mapboxsdk.maps.widgets.MyLocationView; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; /** - * MyBearingTracking exposes different types bearing tracking modes. + * MyBearingTracking exposes different types of bearing tracking modes. + *

+ * These modes visualise the user direction by extracting the direction from either sensor or location data. + *

+ *

+ * Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}. + *

* * @see com.mapbox.mapboxsdk.maps.TrackingSettings#setMyBearingTrackingMode(int) * @see MyLocationView#setMyBearingTrackingMode(int) */ public class MyBearingTracking { - /** - * Indicates that the parameter accepts one of the values from MyBearingTracking. - */ - @IntDef( {NONE, COMPASS, GPS, /**COMBINED**/}) + @IntDef( {NONE, COMPASS, GPS}) @Retention(RetentionPolicy.SOURCE) public @interface Mode { } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java index a1744d701f2..1283283fa50 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/MyLocationTracking.java @@ -3,29 +3,34 @@ import android.support.annotation.IntDef; import com.mapbox.mapboxsdk.maps.MapView; +import com.mapbox.mapboxsdk.maps.MapboxMap; +import com.mapbox.mapboxsdk.maps.TrackingSettings; import com.mapbox.mapboxsdk.maps.widgets.MyLocationView; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; /** - * MyLocationTracking exposes different types of locational tracking modes. + * MyLocationTracking exposes types of location tracking modes. + * *

+ * This allows tracking the user location on screen by updating the camera position when a location update occurs. + *

+ *

+ * Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}. + *

* - * @see com.mapbox.mapboxsdk.maps.TrackingSettings#setMyLocationTrackingMode(int) - * @see MyLocationView#setMyLocationTrackingMode(int) + * @see MapboxMap#setMyLocationEnabled(boolean) + * @see TrackingSettings#setMyLocationTrackingMode(int) */ public class MyLocationTracking { - /** - * Indicates the parameter accepts one of the values from MyLocationTracking. - */ @IntDef( {TRACKING_NONE, TRACKING_FOLLOW}) @Retention(RetentionPolicy.SOURCE) public @interface Mode { } /** - * Location tracking is disabled. + * Tracking the location of the user is disabled. */ public static final int TRACKING_NONE = 0x00000000; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java index 31e6313509c..9943a72e060 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/constants/Style.java @@ -17,7 +17,6 @@ */ public class Style { - /** * Indicates the parameter accepts one of the values from Style. Using one of these * constants means your map style will always use the latest version and may change as we diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java index 7154049bd7f..1f6b0efc4d2 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/IconBitmapChangedException.java @@ -1,15 +1,13 @@ package com.mapbox.mapboxsdk.exceptions; -import android.graphics.Bitmap; - import com.mapbox.mapboxsdk.annotations.Icon; import com.mapbox.mapboxsdk.annotations.Marker; import com.mapbox.mapboxsdk.maps.MapView; /** *

- * A {@code IconBitmapChangedException} is thrown by {@link MapView} when a {@link Marker} is added - * that has a {@link Icon} with a {@link Bitmap} that has been modified since the creation of the Icon. + * An IconBitmapChangedException is thrown by MapView when a Marker is added + * that has an Icon with a Bitmap that has been modified since the creation of the Icon. *

* You cannot modify a {@code Icon} after it has been added to the map in a {@code Marker} * diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java index 08a23a7373f..c1d03858156 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/InvalidLatLngBoundsException.java @@ -1,8 +1,8 @@ package com.mapbox.mapboxsdk.exceptions; /** - * A InvalidLatLngBoundsException is thrown by {@link com.mapbox.mapboxsdk.geometry.LatLngBounds} - * when there aren't enough {@link com.mapbox.mapboxsdk.geometry.LatLng} to create a bounds. + * An InvalidLatLngBoundsException is thrown by LatLngBounds + * when there aren't enough LatLng to create a bounds. */ public class InvalidLatLngBoundsException extends RuntimeException { 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 f0f9b9236b2..44ee83265db 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 @@ -5,6 +5,9 @@ */ public class InvalidMarkerPositionException extends RuntimeException { + /** + * Creates a invalid marker position exception thrown when a Marker object is created with an invalid LatLng position. + */ public InvalidMarkerPositionException() { super("Adding an invalid Marker to a Map. " + "Missing the required position field. " diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/MapboxConfigurationException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/MapboxConfigurationException.java index 74bceb196c7..e9a0261d850 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/MapboxConfigurationException.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/MapboxConfigurationException.java @@ -8,10 +8,14 @@ * This occurs either when {@link com.mapbox.mapboxsdk.Mapbox} is not correctly initialised or the provided access token * through {@link com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)} isn't valid. *

+ * * @see com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String) */ public class MapboxConfigurationException extends RuntimeException { + /** + * Creates a Mapbox configuration exception thrown by MapboxMap when the SDK hasn't been properly initialised. + */ public MapboxConfigurationException() { super("\nUsing MapView requires setting a valid access token. Use Mapbox.getInstance(Context context, " + "String accessToken) to provide one. " diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java index 8923d822f2c..bffc10dc048 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/exceptions/TooManyIconsException.java @@ -1,12 +1,11 @@ package com.mapbox.mapboxsdk.exceptions; -import com.mapbox.mapboxsdk.annotations.Icon; import com.mapbox.mapboxsdk.annotations.IconFactory; /** *

- * A {@code TooManyIconsException} is thrown by {@link IconFactory} when it - * cannot create a {@link Icon} because there are already too many icons created. + * A TooManyIconsException is thrown by IconFactory when it + * cannot create a Icon because there are already too many icons created. *

* You should try to reuse Icon objects whenever possible. * 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 1af8e7cfc76..07df87af3a4 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,12 +1,28 @@ package com.mapbox.mapboxsdk.geometry; /** - * Describes a latitude, longitude point. + * Describes a latitude, longitude, and altitude tuple. */ public interface ILatLng { + + /** + * Get the latitude, in degrees. + * + * @return the latitude value in degrees + */ double getLatitude(); + /** + * Get the longitude, in degrees. + * + * @return the longitude value in degrees + */ double getLongitude(); + /** + * Get the altitude, in meters. + * + * @return the altitude value in meters + */ double getAltitude(); } 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 694c9351434..db459d7cbb4 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 @@ -4,7 +4,19 @@ * Describes a projection in Mercator meters. */ public interface IProjectedMeters { + + /** + * Get the north projection, in meters. + * + * @return the projected meters in north direction + */ double getNorthing(); + /** + * Get the east projection, in meters. + * + * @return the projected meters in east direction + */ double getEasting(); + } 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 ca2d3673b27..eb572411969 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 @@ -3,6 +3,7 @@ import android.location.Location; import android.os.Parcel; import android.os.Parcelable; +import android.support.annotation.FloatRange; import com.mapbox.services.android.telemetry.constants.GeoConstants; import com.mapbox.services.android.telemetry.utils.MathUtils; @@ -21,6 +22,9 @@ */ public class LatLng implements ILatLng, Parcelable { + /** + * Inner class responsible for recreating Parcels into objects. + */ public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { public LatLng createFromParcel(Parcel in) { return new LatLng(in); @@ -44,7 +48,7 @@ public LatLng() { } /** - * Construct a new latitude, longitude point given float arguments + * Construct a new latitude, longitude point given double arguments * * @param latitude Latitude in degrees * @param longitude Longitude in degrees @@ -55,7 +59,7 @@ public LatLng(double latitude, double longitude) { } /** - * Construct a new latitude, longitude, altitude point given float arguments + * Construct a new latitude, longitude, altitude point given double arguments * * @param latitude Latitude in degrees * @param longitude Longitude in degress @@ -68,7 +72,7 @@ public LatLng(double latitude, double longitude, double altitude) { } /** - * Transform a Location into a LatLng point + * Construct a new latitude, longitude, altitude point given location argument * * @param location Android Location */ @@ -77,23 +81,40 @@ public LatLng(Location location) { } /** - * Clone an existing latitude longitude point + * Construct a new latitude, longitude, altitude point given another latitude, longitude, altitude point. * - * @param aLatLng LatLng + * @param latLng LatLng to be cloned. */ - public LatLng(LatLng aLatLng) { - this.latitude = aLatLng.latitude; - this.longitude = aLatLng.longitude; - this.altitude = aLatLng.altitude; + public LatLng(LatLng latLng) { + this.latitude = latLng.latitude; + this.longitude = latLng.longitude; + this.altitude = latLng.altitude; } + /** + * Constructs a new latitude, longitude, altitude tuple given a parcel. + * + * @param in the parcel containing the latitude, longitude, altitude values + */ protected LatLng(Parcel in) { setLatitude(in.readDouble()); setLongitude(in.readDouble()); setAltitude(in.readDouble()); } - public void setLatitude(double latitude) { + /** + * Set the latitude, in degrees. + *

+ * This value is in the range of [-85.05112878, 85.05112878], see {@link GeoConstants#MIN_LATITUDE} and + * {@link GeoConstants#MAX_LATITUDE} + *

+ * + * @param latitude the latitude value in degrees + * @see GeoConstants#MIN_LATITUDE + * @see GeoConstants#MAX_LATITUDE + */ + public void setLatitude( + @FloatRange(from = GeoConstants.MIN_LATITUDE, to = GeoConstants.MAX_LATITUDE) double latitude) { if (Double.isNaN(latitude)) { throw new IllegalArgumentException("latitude must not be NaN"); } @@ -103,12 +124,35 @@ public void setLatitude(double latitude) { this.latitude = latitude; } + /** + * Get the latitude, in degrees. + *

+ * This value is in the range of [-85.05112878, 85.05112878], see {@link GeoConstants#MIN_LATITUDE} and + * {@link GeoConstants#MAX_LATITUDE} + *

+ * + * @return the latitude value in degrees + * @see GeoConstants#MIN_LATITUDE + * @see GeoConstants#MAX_LATITUDE + */ @Override public double getLatitude() { return latitude; } - public void setLongitude(double longitude) { + /** + * Set the longitude, in degrees. + *

+ * This value is in the range of [-180, 180], see {@link GeoConstants#MIN_LONGITUDE} and + * {@link GeoConstants#MAX_LONGITUDE} + *

+ * + * @param longitude the longitude value in degrees + * @see GeoConstants#MIN_LONGITUDE + * @see GeoConstants#MAX_LONGITUDE + */ + public void setLongitude(@FloatRange(from = GeoConstants.MIN_LONGITUDE, to = GeoConstants.MAX_LONGITUDE) + double longitude) { if (Double.isNaN(longitude)) { throw new IllegalArgumentException("longitude must not be NaN"); } @@ -118,15 +162,36 @@ public void setLongitude(double longitude) { this.longitude = longitude; } + /** + * Get the longitude, in degrees. + *

+ * This value is in the range of [-180, 180], see {@link GeoConstants#MIN_LONGITUDE} and + * {@link GeoConstants#MAX_LONGITUDE} + *

+ * + * @return the longitude value in degrees + * @see GeoConstants#MIN_LONGITUDE + * @see GeoConstants#MAX_LONGITUDE + */ @Override public double getLongitude() { return longitude; } + /** + * Set the altitude, in meters. + * + * @param altitude the altitude in meters + */ public void setAltitude(double altitude) { this.altitude = altitude; } + /** + * Get the altitude, in meters. + * + * @return the altitude value in meters + */ @Override public double getAltitude() { return altitude; @@ -136,13 +201,19 @@ public double getAltitude() { * Return a new LatLng object with a wrapped Longitude. This allows original data object * to remain unchanged. * - * @return New LatLng object with wrapped Longitude + * @return new LatLng object with wrapped Longitude */ public LatLng wrap() { longitude = MathUtils.wrap(longitude, GeoConstants.MIN_LONGITUDE, GeoConstants.MAX_LONGITUDE); return this; } + /** + * Indicates whether some other object is "equal to" this one. + * + * @param object The object to compare + * @return True if equal, false if not + */ @Override public boolean equals(Object object) { if (this == object) { @@ -158,6 +229,11 @@ public boolean equals(Object object) { && Double.compare(latLng.longitude, longitude) == 0; } + /** + * Returns a hash code value for the object. + * + * @return the hash code value + */ @Override public int hashCode() { int result; @@ -171,16 +247,32 @@ public int hashCode() { return result; } + /** + * Returns a string representation of the object. + * + * @return the string representation + */ @Override public String toString() { return "LatLng [latitude=" + latitude + ", longitude=" + longitude + ", altitude=" + altitude + "]"; } + /** + * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. + * + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeDouble(latitude); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java index 4a4e2a30aac..505b2db1924 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngBounds.java @@ -3,6 +3,7 @@ import android.os.Parcel; import android.os.Parcelable; import android.support.annotation.NonNull; +import android.support.annotation.Nullable; import com.mapbox.mapboxsdk.exceptions.InvalidLatLngBoundsException; import com.mapbox.services.android.telemetry.constants.GeoConstants; @@ -18,10 +19,10 @@ */ public class LatLngBounds implements Parcelable { - private final double mLatNorth; - private final double mLatSouth; - private final double mLonEast; - private final double mLonWest; + private final double latitudeNorth; + private final double latitudeSouth; + private final double longitudeEast; + private final double longitudeWest; /** * Construct a new LatLngBounds based on its corners, given in NESW @@ -34,10 +35,10 @@ public class LatLngBounds implements Parcelable { */ LatLngBounds(final double northLatitude, final double eastLongitude, final double southLatitude, final double westLongitude) { - this.mLatNorth = northLatitude; - this.mLonEast = eastLongitude; - this.mLatSouth = southLatitude; - this.mLonWest = westLongitude; + this.latitudeNorth = northLatitude; + this.longitudeEast = eastLongitude; + this.latitudeSouth = southLatitude; + this.longitudeWest = westLongitude; } /** @@ -59,8 +60,8 @@ public static LatLngBounds world() { * @return LatLng center of this LatLngBounds */ public LatLng getCenter() { - return new LatLng((this.mLatNorth + this.mLatSouth) / 2, - (this.mLonEast + this.mLonWest) / 2); + return new LatLng((this.latitudeNorth + this.latitudeSouth) / 2, + (this.longitudeEast + this.longitudeWest) / 2); } /** @@ -69,7 +70,7 @@ public LatLng getCenter() { * @return double latitude value for north */ public double getLatNorth() { - return this.mLatNorth; + return this.latitudeNorth; } /** @@ -78,7 +79,7 @@ public double getLatNorth() { * @return double latitude value for south */ public double getLatSouth() { - return this.mLatSouth; + return this.latitudeSouth; } /** @@ -87,7 +88,7 @@ public double getLatSouth() { * @return double longitude value for east */ public double getLonEast() { - return this.mLonEast; + return this.longitudeEast; } /** @@ -96,7 +97,7 @@ public double getLonEast() { * @return double longitude value for west */ public double getLonWest() { - return this.mLonWest; + return this.longitudeWest; } /** @@ -105,7 +106,7 @@ public double getLonWest() { * @return LatLng of the south west corner */ public LatLng getSouthWest() { - return new LatLng(mLatSouth, mLonWest); + return new LatLng(latitudeSouth, longitudeWest); } /** @@ -114,7 +115,7 @@ public LatLng getSouthWest() { * @return LatLng of the north east corner */ public LatLng getNorthEast() { - return new LatLng(mLatNorth, mLonEast); + return new LatLng(latitudeNorth, longitudeEast); } /** @@ -123,7 +124,7 @@ public LatLng getNorthEast() { * @return LatLng of the south east corner */ public LatLng getSouthEast() { - return new LatLng(mLatSouth, mLonEast); + return new LatLng(latitudeSouth, longitudeEast); } /** @@ -132,7 +133,7 @@ public LatLng getSouthEast() { * @return LatLng of the north west corner */ public LatLng getNorthWest() { - return new LatLng(mLatNorth, mLonWest); + return new LatLng(latitudeNorth, longitudeWest); } /** @@ -151,7 +152,7 @@ public LatLngSpan getSpan() { * @return Span distance */ public double getLatitudeSpan() { - return Math.abs(this.mLatNorth - this.mLatSouth); + return Math.abs(this.latitudeNorth - this.latitudeSouth); } /** @@ -161,7 +162,7 @@ public double getLatitudeSpan() { * @return Span distance */ public double getLongitudeSpan() { - return Math.abs(this.mLonEast - this.mLonWest); + return Math.abs(this.longitudeEast - this.longitudeWest); } @@ -174,9 +175,15 @@ public boolean isEmptySpan() { return getLongitudeSpan() == 0.0 || getLatitudeSpan() == 0.0; } + /** + * Returns a string representaton of the object. + * + * @return the string representation + */ @Override public String toString() { - return "N:" + this.mLatNorth + "; E:" + this.mLonEast + "; S:" + this.mLatSouth + "; W:" + this.mLonWest; + return "N:" + this.latitudeNorth + "; E:" + this.longitudeEast + "; S:" + this.latitudeSouth + + "; W:" + this.longitudeWest; } /** @@ -241,10 +248,10 @@ public boolean equals(final Object o) { } if (o instanceof LatLngBounds) { LatLngBounds other = (LatLngBounds) o; - return mLatNorth == other.getLatNorth() - && mLatSouth == other.getLatSouth() - && mLonEast == other.getLonEast() - && mLonWest == other.getLonWest(); + return latitudeNorth == other.getLatNorth() + && latitudeSouth == other.getLatSouth() + && longitudeEast == other.getLonEast() + && longitudeWest == other.getLonWest(); } return false; } @@ -258,10 +265,10 @@ public boolean equals(final Object o) { public boolean contains(final ILatLng latLng) { final double latitude = latLng.getLatitude(); final double longitude = latLng.getLongitude(); - return ((latitude <= this.mLatNorth) - && (latitude >= this.mLatSouth)) - && ((longitude <= this.mLonEast) - && (longitude >= this.mLonWest)); + return ((latitude <= this.latitudeNorth) + && (latitude >= this.latitudeSouth)) + && ((longitude <= this.longitudeEast) + && (longitude >= this.longitudeWest)); } /** @@ -295,10 +302,10 @@ public LatLngBounds union(LatLngBounds bounds) { * @return BoundingBox */ public LatLngBounds union(final double lonNorth, final double latEast, final double lonSouth, final double latWest) { - return new LatLngBounds((this.mLatNorth < lonNorth) ? lonNorth : this.mLatNorth, - (this.mLonEast < latEast) ? latEast : this.mLonEast, - (this.mLatSouth > lonSouth) ? lonSouth : this.mLatSouth, - (this.mLonWest > latWest) ? latWest : this.mLonWest); + return new LatLngBounds((this.latitudeNorth < lonNorth) ? lonNorth : this.latitudeNorth, + (this.longitudeEast < latEast) ? latEast : this.longitudeEast, + (this.latitudeSouth > lonSouth) ? lonSouth : this.latitudeSouth, + (this.longitudeWest > latWest) ? latWest : this.longitudeWest); } /** @@ -307,6 +314,7 @@ public LatLngBounds union(final double lonNorth, final double latEast, final dou * @param box LatLngBounds to intersect with * @return LatLngBounds */ + @Nullable public LatLngBounds intersect(LatLngBounds box) { double minLatWest = Math.max(getLonWest(), box.getLonWest()); double maxLatEast = Math.min(getLonEast(), box.getLonEast()); @@ -334,6 +342,9 @@ public LatLngBounds intersect(double northLatitude, double eastLongitude, double return intersect(new LatLngBounds(northLatitude, eastLongitude, southLatitude, westLongitude)); } + /** + * Inner class responsible for recreating Parcels into objects. + */ public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { @Override @@ -347,25 +358,41 @@ public LatLngBounds[] newArray(final int size) { } }; + /** + * Returns a hash code value for the object. + * + * @return the hash code + */ @Override public int hashCode() { - return (int) ((mLatNorth + 90) - + ((mLatSouth + 90) * 1000) - + ((mLonEast + 180) * 1000000) - + ((mLonEast + 180) * 1000000000)); + return (int) ((latitudeNorth + 90) + + ((latitudeSouth + 90) * 1000) + + ((longitudeEast + 180) * 1000000) + + ((longitudeEast + 180) * 1000000000)); } + /** + * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. + * + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written + */ @Override - public void writeToParcel(final Parcel out, final int arg1) { - out.writeDouble(this.mLatNorth); - out.writeDouble(this.mLonEast); - out.writeDouble(this.mLatSouth); - out.writeDouble(this.mLonWest); + public void writeToParcel(final Parcel out, final int flags) { + out.writeDouble(this.latitudeNorth); + out.writeDouble(this.longitudeEast); + out.writeDouble(this.latitudeSouth); + out.writeDouble(this.longitudeWest); } private static LatLngBounds readFromParcel(final Parcel in) { @@ -381,28 +408,51 @@ private static LatLngBounds readFromParcel(final Parcel in) { */ public static final class Builder { - private List mLatLngList; + private List latLngList; + /** + * Constructs a builder to compose LatLng objects to a LatLngBounds. + */ public Builder() { - mLatLngList = new ArrayList<>(); + latLngList = new ArrayList<>(); } + /** + * Builds a new LatLngBounds. + *

+ * Throws an {@link InvalidLatLngBoundsException} when no LatLngBounds can be created. + *

+ * + * @return the build LatLngBounds + */ public LatLngBounds build() { - if (mLatLngList.size() < 2) { - throw new InvalidLatLngBoundsException(mLatLngList.size()); + if (latLngList.size() < 2) { + throw new InvalidLatLngBoundsException(latLngList.size()); } - return LatLngBounds.fromLatLngs(mLatLngList); + return LatLngBounds.fromLatLngs(latLngList); } + /** + * Adds a LatLng object to the LatLngBounds.Builder. + * + * @param latLngs the List of LatLng objects to be added + * @return this + */ public Builder includes(List latLngs) { for (LatLng point : latLngs) { - mLatLngList.add(point); + latLngList.add(point); } return this; } + /** + * Adds a LatLng object to the LatLngBounds.Builder. + * + * @param latLng the LatLng to be added + * @return this + */ public Builder include(@NonNull LatLng latLng) { - mLatLngList.add(latLng); + latLngList.add(latLng); return this; } } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngSpan.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngSpan.java index d00ccdb9b83..322c7dfb74a 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngSpan.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/LatLngSpan.java @@ -64,19 +64,28 @@ public void setLongitudeSpan(double longitudeSpan) { mLongitudeSpan = longitudeSpan; } + /** + * Indicates whether some other object is "equal to" this one. + * + * @param object The object to compare + * @return True if equal, false if not + */ @Override - public boolean equals(Object o) { - if (this == o) { + public boolean equals(Object object) { + if (this == object) { return true; } - if (o instanceof LatLngSpan) { - LatLngSpan other = (LatLngSpan) o; + if (object instanceof LatLngSpan) { + LatLngSpan other = (LatLngSpan) object; return mLongitudeSpan == other.getLongitudeSpan() && mLatitudeSpan == other.getLatitudeSpan(); } return false; } + /** + * Inner class responsible for recreating Parcels into objects. + */ public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { @Override @@ -90,14 +99,41 @@ public LatLngSpan[] newArray(int size) { } }; + /** + * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. + * + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out Parcel in which the object should be written + * @param flags Additional flags about how the object should be written + */ @Override - public void writeToParcel(Parcel out, int arg1) { + public void writeToParcel(Parcel out, int flags) { out.writeDouble(mLatitudeSpan); out.writeDouble(mLongitudeSpan); } + + /** + * Returns a hash code value for the object. + * + * @return hash code value of this + */ + @Override + public int hashCode() { + int result; + long temp; + temp = Double.doubleToLongBits(mLatitudeSpan); + result = (int) (temp ^ (temp >>> 32)); + temp = Double.doubleToLongBits(mLongitudeSpan); + result = 31 * result + (int) (temp ^ (temp >>> 32)); + return result; + } } 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 761d8f2a8bb..fa84c33b2b9 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 @@ -13,6 +13,9 @@ */ public class ProjectedMeters implements IProjectedMeters, Parcelable { + /** + * Inner class responsible for recreating Parcels into objects. + */ public static final Creator CREATOR = new Creator() { public ProjectedMeters createFromParcel(Parcel in) { return new ProjectedMeters(in); @@ -47,6 +50,12 @@ public ProjectedMeters(ProjectedMeters projectedMeters) { this.easting = projectedMeters.easting; } + /** + * Creates a ProjectedMeters from a Parcel. + * + * @param in The parcel to create from + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ private ProjectedMeters(Parcel in) { northing = in.readDouble(); easting = in.readDouble(); @@ -72,22 +81,32 @@ public double getEasting() { return easting; } + /** + * Indicates whether some other object is "equal to" this one. + * + * @param other The object to compare this to + * @return true if equal, false if not + */ @Override - public boolean equals(Object o) { - if (this == o) { + public boolean equals(Object other) { + if (this == other) { return true; } - if (o == null || getClass() != o.getClass()) { + if (other == null || getClass() != other.getClass()) { return false; } - ProjectedMeters projectedMeters = (ProjectedMeters) o; + ProjectedMeters projectedMeters = (ProjectedMeters) other; return Double.compare(projectedMeters.easting, easting) == 0 && Double.compare(projectedMeters.northing, northing) == 0; - } + /** + * Returns a hash code value for the object. + * + * @return the hash code of this + */ @Override public int hashCode() { int result; @@ -99,16 +118,32 @@ public int hashCode() { return result; } + /** + * Returns a string representation of the object. + * + * @return the string representation of this + */ @Override public String toString() { return "ProjectedMeters [northing=" + northing + ", easting=" + easting + "]"; } + /** + * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. + * + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeDouble(northing); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/VisibleRegion.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/VisibleRegion.java index c5b8ad3077a..c09c00fcedf 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/VisibleRegion.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/VisibleRegion.java @@ -37,6 +37,11 @@ public class VisibleRegion implements Parcelable { */ public final LatLngBounds latLngBounds; + /** + * Creates a VisibleRegion from a Parcel. + * + * @param in The Parcel to create this from + */ private VisibleRegion(Parcel in) { this.farLeft = in.readParcelable(LatLng.class.getClassLoader()); this.farRight = in.readParcelable(LatLng.class.getClassLoader()); @@ -46,7 +51,7 @@ private VisibleRegion(Parcel in) { } /** - * Creates a new VisibleRegion given the four corners of the camera. + * Creates a VisibleRegion given the four corners of the camera. * * @param farLeft A LatLng object containing the latitude and longitude of the near left corner of the region. * @param farRight A LatLng object containing the latitude and longitude of the near left corner of the region. @@ -88,12 +93,22 @@ public boolean equals(Object o) { && latLngBounds.equals(visibleRegion.latLngBounds); } + /** + * The string representation of the object. + * + * @return the string representation of this + */ @Override public String toString() { return "[farLeft [" + farLeft + "], farRight [" + farRight + "], nearLeft [" + nearLeft + "], nearRight [" + nearRight + "], latLngBounds [" + latLngBounds + "]]"; } + /** + * Returns a hash code value for the object. + * + * @return the hash code + */ @Override public int hashCode() { return ((farLeft.hashCode() + 90) @@ -102,11 +117,22 @@ public int hashCode() { + ((nearRight.hashCode() + 180) * 1000000000)); } + /** + * Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. + * + * @return a bitmask indicating the set of special object types marshaled by this Parcelable object instance. + */ @Override public int describeContents() { return 0; } + /** + * Flatten this object in to a Parcel. + * + * @param out The Parcel in which the object should be written. + * @param flags Additional flags about how the object should be written + */ @Override public void writeToParcel(Parcel out, int flags) { out.writeParcelable(farLeft, flags); @@ -116,6 +142,9 @@ public void writeToParcel(Parcel out, int flags) { out.writeParcelable(latLngBounds, flags); } + /** + * Inner class responsible for recreating Parcels into objects. + */ public static final Parcelable.Creator CREATOR = new Parcelable.Creator() { public VisibleRegion createFromParcel(Parcel in) { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java index 8416bd5b6cf..12e33004296 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationSource.java @@ -28,12 +28,16 @@ * in the history stack. *

*/ -public class LocationSource extends LocationEngine implements - LostApiClient.ConnectionCallbacks, LocationListener { +public class LocationSource extends LocationEngine implements LostApiClient.ConnectionCallbacks, LocationListener { private Context context; private LostApiClient lostApiClient; + /** + * Constructs a location source instance. + * + * @param context the context from which the Application context will be derived. + */ public LocationSource(Context context) { super(); this.context = context.getApplicationContext(); 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 098c701e033..c51d9327d2a 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 @@ -1,7 +1,5 @@ package com.mapbox.mapboxsdk.maps; -import android.app.Activity; -import android.app.Fragment; import android.content.Context; import android.graphics.Canvas; import android.graphics.PointF; @@ -27,7 +25,6 @@ import android.widget.ImageView; import android.widget.ZoomButtonsController; -import com.mapbox.mapboxsdk.Mapbox; import com.mapbox.mapboxsdk.R; import com.mapbox.mapboxsdk.annotations.MarkerViewManager; import com.mapbox.mapboxsdk.constants.MapboxConstants; @@ -178,14 +175,14 @@ private void initialise(@NonNull final Context context, @NonNull final MapboxMap /** *

- * You must call this method from the parent's {@link android.app.Activity#onCreate(Bundle)} or - * {@link android.app.Fragment#onCreate(Bundle)}. + * You must call this method from the parent's Activity#onCreate(Bundle)} or + * Fragment#onCreate(Bundle). *

- * You must set a valid access token with {@link Mapbox#getInstance(Context, String)}) before you call this method - * or an exception will be thrown. + * You must set a valid access token with {@link com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String)} + * before you call this method or an exception will be thrown. * * @param savedInstanceState Pass in the parent's savedInstanceState. - * @see Mapbox#getInstance(Context, String) + * @see com.mapbox.mapboxsdk.Mapbox#getInstance(Context, String) */ @UiThread public void onCreate(@Nullable Bundle savedInstanceState) { @@ -214,12 +211,11 @@ private void initialiseDrawingSurface(boolean textureMode) { } /** - * You must call this method from the parent's {@link android.app.Activity#onSaveInstanceState(Bundle)} - * or {@link android.app.Fragment#onSaveInstanceState(Bundle)}. + * You must call this method from the parent's Activity#onSaveInstanceState(Bundle) + * or Fragment#onSaveInstanceState(Bundle). * * @param outState Pass in the parent's outState. */ - @UiThread public void onSaveInstanceState(@NonNull Bundle outState) { outState.putBoolean(MapboxConstants.STATE_HAS_SAVED_STATE, true); @@ -227,7 +223,7 @@ public void onSaveInstanceState(@NonNull Bundle outState) { } /** - * You must call this method from the parent's {@link Activity#onStart()} or {@link Fragment#onStart()} + * You must call this method from the parent's Activity#onStart() or Fragment#onStart() */ @UiThread public void onStart() { @@ -236,7 +232,7 @@ public void onStart() { } /** - * You must call this method from the parent's {@link Activity#onResume()} or {@link Fragment#onResume()}. + * You must call this method from the parent's Activity#onResume() or Fragment#onResume(). */ @UiThread public void onResume() { @@ -244,7 +240,7 @@ public void onResume() { } /** - * You must call this method from the parent's {@link Activity#onPause()} or {@link Fragment#onPause()}. + * You must call this method from the parent's Activity#onPause() or Fragment#onPause(). */ @UiThread public void onPause() { @@ -252,7 +248,7 @@ public void onPause() { } /** - * You must call this method from the parent's {@link Activity#onStop()} or {@link Fragment#onStop()}. + * You must call this method from the parent's Activity#onStop() or Fragment#onStop(). */ @UiThread public void onStop() { @@ -261,7 +257,7 @@ public void onStop() { } /** - * You must call this method from the parent's {@link Activity#onDestroy()} or {@link Fragment#onDestroy()}. + * You must call this method from the parent's Activity#onDestroy() or Fragment#onDestroy(). */ @UiThread public void onDestroy() { @@ -325,7 +321,7 @@ public boolean onHoverEvent(MotionEvent event) { } /** - * You must call this method from the parent's {@link Activity#onLowMemory()} or {@link Fragment#onLowMemory()}. + * You must call this method from the parent's Activity#onLowMemory() or Fragment#onLowMemory(). */ @UiThread public void onLowMemory() { 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 8a708cb1869..d672ab37c36 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 @@ -736,8 +736,8 @@ public final void easeCamera(CameraUpdate update, int durationMs, boolean easing * will return the current location of the camera in flight. *

* Note that this will cancel location tracking mode if enabled. You can change this behaviour by calling - * {@link TrackingSettings#setDismissTrackingModeForCameraPositionChange(boolean)} with false before invoking this - * method and calling it with true in the {@link CancelableCallback#onFinish()}. + * {@link com.mapbox.mapboxsdk.maps.TrackingSettings#setDismissLocationTrackingOnGesture(boolean)} with false before + * invoking this method and calling it with true in the {@link CancelableCallback#onFinish()}. *

* * @param update The change that should be applied to the camera. @@ -763,8 +763,8 @@ public final void easeCamera(final CameraUpdate update, final int durationMs, fi * will return the current location of the camera in flight. *

* Note that this will cancel location tracking mode if enabled. You can change this behaviour by calling - * {@link TrackingSettings#setDismissTrackingModeForCameraPositionChange(boolean)} with false before invoking this - * method and calling it with true in the {@link CancelableCallback#onFinish()}. + * {@link com.mapbox.mapboxsdk.maps.TrackingSettings#setDismissLocationTrackingOnGesture(boolean)} with false before + * invoking this method and calling it with true in the {@link CancelableCallback#onFinish()}. *

* * @param update The change that should be applied to the camera. @@ -887,7 +887,12 @@ public void resetNorth() { } /** - * Set focal bearing. + * Transform the map bearing given a bearing, focal point coordinates, and a duration. + * + * @param bearing The bearing of the Map to be transformed to + * @param focalX The x coordinate of the focal point + * @param focalY The y coordinate of the focal point + * @param duration The duration of the transformation */ public void setFocalBearing(double bearing, float focalX, float focalY, long duration) { transform.setBearing(bearing, focalX, focalY, duration); @@ -1059,7 +1064,7 @@ public void onMapChanged(@MapView.MapChange int change) { * 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}. + * @param style The bundled style. * @see Style */ @UiThread @@ -1075,7 +1080,8 @@ public void setStyle(@Style.StyleUrl String style) { * 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}. + * @param style The bundled style. + * @param callback The callback to be invoked when the style has finished loading * @see Style */ @UiThread @@ -1576,9 +1582,11 @@ public void setLatLngBoundsForCameraTarget(@Nullable LatLngBounds latLngBounds) } /** - * Gets a camera position that would fit a bounds. + * Get a camera position that fits a provided bounds and padding. * * @param latLngBounds the bounds to constrain the map with + * @param padding the padding to apply to the bounds + * @return the camera position that fits the bounds and padding */ public CameraPosition getCameraForLatLngBounds(@Nullable LatLngBounds latLngBounds, int[] padding) { // calculate and set additional bounds padding @@ -2410,11 +2418,13 @@ public interface SnapshotReadyCallback { } /** - * Interface definintion for a callback to be invoked when the style has finished loading. + * Interface definition for a callback to be invoked when the style has finished loading. */ public interface OnStyleLoadedListener { /** - * Invoked when the style has finished loading. + * Invoked when the style has finished loading + * + * @param style the style that has been loaded */ void onStyleLoaded(String style); } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java index 98f94ddb39a..2efed1b322d 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java @@ -378,7 +378,7 @@ public MapboxMapOptions compassEnabled(boolean enabled) { /** * Specifies the gravity state of mapbox_compass_icon for a map view. * - * @param gravity see {@link android.view.Gravity} + * @param gravity Android SDK Gravity. * @return This */ public MapboxMapOptions compassGravity(int gravity) { @@ -439,7 +439,7 @@ public MapboxMapOptions logoEnabled(boolean enabled) { /** * Specifies the gravity state of logo for a map view. * - * @param gravity see {@link android.view.Gravity} + * @param gravity Android SDK Gravity. * @return This */ public MapboxMapOptions logoGravity(int gravity) { @@ -472,7 +472,7 @@ public MapboxMapOptions attributionEnabled(boolean enabled) { /** * Specifies the gravity state of attribution for a map view. * - * @param gravity see {@link android.view.Gravity} + * @param gravity Android SDK Gravity. * @return This */ public MapboxMapOptions attributionGravity(int gravity) { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java index accecf232b7..7f8ba21e3ea 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java @@ -16,7 +16,6 @@ import android.support.annotation.UiThread; import android.support.v4.content.ContextCompat; import android.support.v4.content.res.ResourcesCompat; -import android.view.Gravity; import android.view.View; import android.widget.FrameLayout; import android.widget.ImageView; @@ -196,7 +195,7 @@ private void initialiseLogo(MapboxMapOptions options, Resources resources) { setLogoMargins(resources, options.getLogoMargins()); } - private void setLogoMargins(Resources resources, int[]logoMargins) { + private void setLogoMargins(Resources resources, int[] logoMargins) { if (logoMargins != null) { setLogoMargins(logoMargins[0], logoMargins[1], logoMargins[2], logoMargins[3]); } else { @@ -309,8 +308,7 @@ public boolean isCompassEnabled() { *

* By default, the compass is in the top right corner. * - * @param gravity One of the values from {@link Gravity}. - * @see Gravity + * @param gravity Android SDK Gravity. */ @UiThread public void setCompassGravity(int gravity) { @@ -454,8 +452,7 @@ public boolean isLogoEnabled() { *

* By default, the logo is in the bottom left corner. * - * @param gravity One of the values from {@link Gravity}. - * @see Gravity + * @param gravity Android SDK Gravity. */ public void setLogoGravity(int gravity) { setWidgetGravity(logoView, gravity); @@ -546,8 +543,7 @@ public boolean isAttributionEnabled() { *

* By default, the attribution is in the bottom left corner next to the Mapbox logo. * - * @param gravity One of the values from {@link Gravity}. - * @see Gravity + * @param gravity Android SDK Gravity. */ public void setAttributionGravity(int gravity) { setWidgetGravity(attributionsView, gravity); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationView.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationView.java index 9740679cf59..72868a91d86 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationView.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationView.java @@ -45,6 +45,9 @@ /** * UI element overlaid on a map to show the user's location. + *

+ * Use {@link MyLocationViewSettings} to manipulate the state of this view. + *

*/ public class MyLocationView extends View { @@ -155,6 +158,12 @@ public void init(LocationSource locationSource) { this.locationSource = locationSource; } + /** + * Set the foreground drawable, for internal use only. + * + * @param defaultDrawable The drawable shown when showing this view + * @param bearingDrawable The drawable shown when tracking of bearing is enabled + */ public final void setForegroundDrawables(Drawable defaultDrawable, Drawable bearingDrawable) { if (defaultDrawable == null) { return; @@ -183,6 +192,11 @@ public final void setForegroundDrawables(Drawable defaultDrawable, Drawable bear invalidateBounds(); } + /** + * Set the foreground drawable tint, for internal use only. + * + * @param color The color to tint the drawable with + */ public final void setForegroundDrawableTint(@ColorInt int color) { if (foregroundDrawable != null) { foregroundDrawable.mutate().setColorFilter(color, PorterDuff.Mode.SRC_IN); @@ -193,10 +207,24 @@ public final void setForegroundDrawableTint(@ColorInt int color) { invalidate(); } + /** + * Set the shadow drawable, for internal use only. + * + * @param drawable The drawable shown as shadow + */ public final void setShadowDrawable(Drawable drawable) { setShadowDrawable(drawable, 0, 0, 0, 0); } + /** + * Set the shadow drawable with some additional offset. + * + * @param drawable The drawable shown as shadow + * @param left The left offset margin + * @param top The top offset margin + * @param right The right offset margin + * @param bottom The bottom offset margin + */ public final void setShadowDrawable(Drawable drawable, int left, int top, int right, int bottom) { if (drawable != null) { backgroundDrawable = drawable; @@ -210,6 +238,11 @@ public final void setShadowDrawable(Drawable drawable, int left, int top, int ri invalidateBounds(); } + /** + * Set the shadow drawable tint color, for internal use only. + * + * @param color The tint color to apply + */ public final void setShadowDrawableTint(@ColorInt int color) { if (backgroundDrawable == null) { return; @@ -218,6 +251,11 @@ public final void setShadowDrawableTint(@ColorInt int color) { invalidate(); } + /** + * Set the accuracy tint color, for internal use only. + * + * @param color The tint color to apply + */ public final void setAccuracyTint(@ColorInt int color) { int alpha = accuracyPaint.getAlpha(); accuracyPaint.setColor(color); @@ -225,6 +263,11 @@ public final void setAccuracyTint(@ColorInt int color) { invalidate(); } + /** + * Set the accuracy alpha value, for internal use only. + * + * @param alpha The alpha accuracy value to apply + */ public final void setAccuracyAlpha(@IntRange(from = 0, to = 255) int alpha) { accuracyPaint.setAlpha(alpha); invalidate(); @@ -314,6 +357,11 @@ protected void onDraw(Canvas canvas) { } } + /** + * Set the tilt value, for internal use only. + * + * @param tilt The tilt to apply + */ public void setTilt(@FloatRange(from = 0, to = 60.0f) double tilt) { this.tilt = tilt; if (myLocationTrackingMode == MyLocationTracking.TRACKING_FOLLOW) { @@ -322,6 +370,11 @@ public void setTilt(@FloatRange(from = 0, to = 60.0f) double tilt) { invalidate(); } + /** + * Set the bearing value, for internal use only. + * + * @param bearing The bearing to apply + */ public void setBearing(double bearing) { this.bearing = bearing; if (myLocationTrackingMode == MyLocationTracking.TRACKING_NONE) { @@ -335,6 +388,11 @@ public void setBearing(double bearing) { } } + /** + * Set the bearing and tilt from a camera position, for internal use only. + * + * @param position The camera position to extract bearing and tilt from + */ public void setCameraPosition(CameraPosition position) { if (position != null) { setBearing(position.bearing); @@ -342,6 +400,9 @@ public void setCameraPosition(CameraPosition position) { } } + /** + * Called when the hosting activity is starting, for internal use only. + */ public void onStart() { if (myBearingTrackingMode == MyBearingTracking.COMPASS && compassListener.isSensorAvailable()) { compassListener.onResume(); @@ -351,6 +412,9 @@ public void onStart() { } } + /** + * Called when the hosting activity is stopping, for internal use only. + */ public void onStop() { compassListener.onPause(); toggleGps(false); @@ -382,6 +446,9 @@ protected void onDetachedFromWindow() { } } + /** + * Update current locationstate. + */ public void update() { if (isEnabled()) { myLocationBehavior.invalidate(); @@ -396,17 +463,33 @@ public void setMapboxMap(MapboxMap mapboxMap) { this.projection = mapboxMap.getProjection(); } + /** + * Set the enabled state, for internal use only. + * + * @param enabled The value to set the state to + */ @Override public void setEnabled(boolean enabled) { setEnabled(enabled, false); } + /** + * Set the enabled state, for internal use only. + * + * @param enabled The value to set the state to + * @param isCustomLocationSource Flag handling for handling user provided custom location source + */ public void setEnabled(boolean enabled, boolean isCustomLocationSource) { super.setEnabled(enabled); setVisibility(enabled ? View.VISIBLE : View.INVISIBLE); toggleGps(enabled, isCustomLocationSource); } + /** + * Save the view instance state, for internal use only. + * + * @return the marshaled representation of the view state + */ @Override protected Parcelable onSaveInstanceState() { Bundle bundle = new Bundle(); @@ -415,6 +498,11 @@ protected Parcelable onSaveInstanceState() { return bundle; } + /** + * Restore the view instance state, for internal use only. + * + * @param state the marshalled representation of the state to restore + */ @Override public void onRestoreInstanceState(Parcelable state) { if (state instanceof Bundle) { @@ -430,7 +518,7 @@ private void toggleGps(boolean enableGps) { } /** - * Enabled / Disable GPS location updates along with updating the UI + * Enabled / Disable GPS location updates along with updating the UI, for internal use only. * * @param enableGps true if GPS is to be enabled, false if GPS is to be disabled */ @@ -463,10 +551,20 @@ private void toggleGps(boolean enableGps, boolean isCustomLocationSource) { } } + /** + * Get the current location. + * + * @return the current location + */ public Location getLocation() { return location; } + /** + * Set the current location, for internal use only. + * + * @param location The current location + */ public void setLocation(Location location) { if (location == null) { this.location = null; @@ -482,10 +580,20 @@ public void setLocation(Location location) { } } + /** + * Set location change animation enabled, for internal use only. + * + * @param locationChangeAnimationEnabled True if location changes are animated + */ public void setLocationChangeAnimationEnabled(boolean locationChangeAnimationEnabled) { this.locationChangeAnimationEnabled = locationChangeAnimationEnabled; } + /** + * Set the bearing tracking mode, for internal use only. + * + * @param myBearingTrackingMode The bearing tracking mode + */ public void setMyBearingTrackingMode(@MyBearingTracking.Mode int myBearingTrackingMode) { this.myBearingTrackingMode = myBearingTrackingMode; if (myBearingTrackingMode == MyBearingTracking.COMPASS && compassListener.isSensorAvailable()) { @@ -502,6 +610,11 @@ public void setMyBearingTrackingMode(@MyBearingTracking.Mode int myBearingTracki invalidate(); } + /** + * Set the location tracking mode, for internla use only. + * + * @param myLocationTrackingMode The location tracking mode + */ public void setMyLocationTrackingMode(@MyLocationTracking.Mode int myLocationTrackingMode) { MyLocationBehaviorFactory factory = new MyLocationBehaviorFactory(); myLocationBehavior = factory.getBehavioralModel(myLocationTrackingMode); @@ -522,17 +635,32 @@ public void setMyLocationTrackingMode(@MyLocationTracking.Mode int myLocationTra invalidate(); } + /** + * Get the location tracking mode, for internal use only. + * + * @return The location tracking mode + */ @MyLocationTracking.Mode public int getMyLocationTrackingMode() { return myLocationTrackingMode; } + /** + * Get the bearing tracking mode, for internal use only. + * + * @return the bearing tracking mode + */ @MyBearingTracking.Mode public int getMyBearingTrackingMode() { return myBearingTrackingMode; } + /** + * Set the compass bearing value, for internal use only. + * + * @param bearing The compas bearing value + */ private void setCompass(double bearing) { setCompass(bearing, 0 /* no animation */); } @@ -560,14 +688,29 @@ private void setCompass(double bearing, long duration) { directionAnimator.start(); } + /** + * Get the center of this view in screen coordinates. + * + * @return the center of the view + */ public PointF getCenter() { return new PointF(getCenterX(), getCenterY()); } + /** + * Get the x value of the center of this view. + * + * @return the x value of the center of the view + */ private float getCenterX() { return (getX() + getMeasuredWidth()) / 2 + contentPaddingX - projectedX; } + /** + * Get the y value of the center of this view. + * + * @return the y value of the center of the view + */ private float getCenterY() { return (getY() + getMeasuredHeight()) / 2 + contentPaddingY - projectedY; } @@ -577,6 +720,11 @@ public void setContentPadding(int[] padding) { contentPaddingY = (padding[1] - padding[3]) / 2; } + /** + * Set the location source from which location updates are received, for internal use only. + * + * @param locationSource The location source to receive updates from + */ public void setLocationSource(LocationEngine locationSource) { toggleGps(false); this.locationSource = locationSource; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationViewSettings.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationViewSettings.java index e9d823ebda6..2ad1bf7ebc0 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationViewSettings.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/widgets/MyLocationViewSettings.java @@ -5,9 +5,9 @@ import android.support.annotation.IntRange; import android.support.annotation.NonNull; +import com.mapbox.mapboxsdk.camera.CameraPosition; import com.mapbox.mapboxsdk.constants.MyLocationTracking; import com.mapbox.mapboxsdk.maps.FocalPointChangeListener; -import com.mapbox.mapboxsdk.camera.CameraPosition; import com.mapbox.mapboxsdk.maps.MapboxMapOptions; import com.mapbox.mapboxsdk.maps.Projection; @@ -77,6 +77,11 @@ public MyLocationViewSettings(MyLocationView myLocationView, Projection projecti this.focalPointChangeListener = focalPointChangedListener; } + /** + * Initialise this with MapboxMapOptions. + * + * @param options the options to initialise this class from + */ public void initialise(@NonNull MapboxMapOptions options) { CameraPosition position = options.getCamera(); if (position != null && !position.equals(CameraPosition.DEFAULT)) { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/net/ConnectivityReceiver.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/net/ConnectivityReceiver.java index 7be56fa6948..a1bd98b7805 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/net/ConnectivityReceiver.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/net/ConnectivityReceiver.java @@ -24,7 +24,10 @@ public class ConnectivityReceiver extends BroadcastReceiver { private static ConnectivityReceiver INSTANCE; /** - * Get or create the singleton instance + * Get a single instance of ConnectivityReceiver. + * + * @param context the context to extract the application context from + * @return single instance of ConnectivityReceiver */ public static synchronized ConnectivityReceiver instance(Context context) { if (INSTANCE == null) { @@ -74,7 +77,7 @@ public void deactivate() { } /** - * @see BroadcastReceiver#onReceive(Context, Intent) + * {@inheritDoc} */ @Override public void onReceive(Context context, Intent intent) { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java index 95cb7d66c43..d572d696db8 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java @@ -115,6 +115,12 @@ public void run() { }).start(); } + /** + * Get the single instance of offline manager. + * + * @param context the context used to host the offline manager + * @return the single instance of offline manager + */ public static synchronized OfflineManager getInstance(Context context) { if (instance == null) { instance = new OfflineManager(context); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java index baa815491fa..1c78d5979e3 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegion.java @@ -393,6 +393,7 @@ public void run() { * After you call this method, you may not call any additional methods on this object. *

* + * @param bytes the metadata in bytes * @param callback the callback to be invoked */ public void updateMetadata(@NonNull final byte[] bytes, @NonNull final OfflineRegionUpdateMetadataCallback callback) { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegionStatus.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegionStatus.java index 9c3655fbec7..fe12dd46c4b 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegionStatus.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineRegionStatus.java @@ -7,6 +7,7 @@ *

* Note that the total required size in bytes is not currently available. A * future API release may provide an estimate of this number. + *

*/ public class OfflineRegionStatus { @@ -51,6 +52,7 @@ public class OfflineRegionStatus { * Specifically, it is false during early phases of an offline download. Once * style and tile sources have been downloaded, it is possible to calculate the * precise number of required resources, at which point it is set to true. + *

*/ private boolean requiredResourceCountIsPrecise = true; @@ -73,37 +75,93 @@ private OfflineRegionStatus(int downloadState, long completedResourceCount, } /** - * Is the region complete? + * Validates if the region download has completed + * + * @return true if download is complete, false if not */ public boolean isComplete() { return (completedResourceCount == requiredResourceCount); } + /** + * Returns the download state. + *

+ * State is defined as + *

+ *
    + *
  • {@link OfflineRegion#STATE_ACTIVE}
    • + *
  • {@link OfflineRegion#STATE_INACTIVE}
    • + *
+ * + * @return the download state. + */ @OfflineRegion.DownloadState public int getDownloadState() { return downloadState; } + /** + * Get the number of resources (inclusive of tiles) that have been fully downloaded + * and are ready for offline access. + * + * @return the amount of resources that have finished downloading. + */ public long getCompletedResourceCount() { return completedResourceCount; } + /** + * The cumulative size, in bytes, of all resources (inclusive of tiles) that have + * been fully downloaded. + * + * @return the size of the resources that have finished downloading + */ public long getCompletedResourceSize() { return completedResourceSize; } + /** + * Get the number of tiles that have been fully downloaded and are ready for + * offline access. + * + * @return the completed tile count + */ public long getCompletedTileCount() { return completedTileCount; } + /** + * Get the cumulative size, in bytes, of all tiles that have been fully downloaded. + * + * @return the completed tile size + */ public long getCompletedTileSize() { return completedTileSize; } + /** + * Get the number of resources that are known to be required for this region. See the + * documentation for `requiredResourceCountIsPrecise` for an important caveat + * about this number. + * + * @return the amount of resources that are required + */ public long getRequiredResourceCount() { return requiredResourceCount; } + /** + * Returns when the value of requiredResourceCount is a precise + * count of the number of required resources, and false when it is merely a lower + * bound. + *

+ * Specifically, it is false during early phases of an offline download. Once + * style and tile sources have been downloaded, it is possible to calculate the + * precise number of required resources, at which point it is set to true. + *

+ * + * @return True if the required resource count is precise, false if not + */ public boolean isRequiredResourceCountPrecise() { return requiredResourceCountIsPrecise; } diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/FileSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/FileSource.java index 06676d76a1b..eafef80e8d1 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/FileSource.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/storage/FileSource.java @@ -3,9 +3,9 @@ import android.content.Context; import android.content.pm.ApplicationInfo; import android.content.pm.PackageManager; +import android.content.res.AssetManager; import android.os.Environment; import android.support.annotation.NonNull; -import android.content.res.AssetManager; import com.mapbox.mapboxsdk.Mapbox; import com.mapbox.mapboxsdk.constants.MapboxConstants; @@ -28,8 +28,9 @@ public interface ResourceTransformCallback { /** * Called whenever a URL needs to be transformed. * - * @param kind The kind of URL to be transformed. - * @return A URL that will now be downloaded. + * @param kind the kind of URL to be transformed. + * @param url the URL to be transformed + * @return a URL that will now be downloaded. */ String onURL(@Resource.Kind int kind, String url); @@ -38,6 +39,12 @@ public interface ResourceTransformCallback { // File source instance is kept alive after initialization private static FileSource INSTANCE; + /** + * Get the single instance of FileSource. + * + * @param context the context to derive the cache path from + * @return the single instance of FileSource + */ public static synchronized FileSource getInstance(Context context) { if (INSTANCE == null) { String cachePath = getCachePath(context); @@ -47,6 +54,12 @@ public static synchronized FileSource getInstance(Context context) { return INSTANCE; } + /** + * Get the cache path for a context. + * + * @param context the context to derive the cache path from + * @return the cache path + */ public static String getCachePath(Context context) { // Default value boolean setStorageExternal = MapboxConstants.DEFAULT_SET_STORAGE_EXTERNAL; diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/PropertyValue.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/PropertyValue.java index 68727c8a4fc..a57c440df4e 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/PropertyValue.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/PropertyValue.java @@ -30,14 +30,29 @@ public PropertyValue(@NonNull String name, T value) { this.value = value; } + /** + * Returns if this is null + * + * @return true if this is null, false if not + */ public boolean isNull() { return value == null; } + /** + * Returns if this is a function. + * + * @return true if is a function, false if not + */ public boolean isFunction() { return !isNull() && value instanceof Function; } + /** + * Returns if this is a value. + * + * @return true if is a value, false if not + */ public boolean isValue() { return !isNull() && !isFunction(); } @@ -53,6 +68,11 @@ public Function getFunction() { } } + /** + * Get the value of the property. + * + * @return the property value + */ @Nullable public T getValue() { if (isValue()) { @@ -64,6 +84,11 @@ public T getValue() { } } + /** + * Get the color int value of the property if the value is a color. + * + * @return the color int value of the property, null if not a color value + */ @ColorInt @Nullable public Integer getColorInt() { @@ -80,6 +105,11 @@ public Integer getColorInt() { } } + /** + * Get the string representation of a property value. + * + * @return the string representation + */ @Override public String toString() { return String.format("%s: %s", name, value); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Light.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Light.java index b66a50b8a4d..cb6465a6b13 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Light.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Light.java @@ -13,7 +13,7 @@ /** * The global light source. * - * @see The online documentation + * @see The online documentation */ @UiThread public class Light { @@ -43,7 +43,8 @@ public void setAnchor(@Property.ANCHOR String anchor) { * * @return anchor as String */ - @Property.ANCHOR public String getAnchor() { + @Property.ANCHOR + public String getAnchor() { return nativeGetAnchor(); } @@ -106,7 +107,7 @@ public void setColor(String color) { * * @return color as String */ - public String getColor() { + public String getColor() { return nativeGetColor(); } @@ -142,7 +143,7 @@ public void setIntensity(float intensity) { * * @return intensity as Float */ - public float getIntensity() { + public float getIntensity() { return nativeGetIntensity(); } @@ -165,17 +166,30 @@ public void setIntensityTransition(TransitionOptions options) { } private native void nativeSetAnchor(String anchor); + private native String nativeGetAnchor(); + private native void nativeSetPosition(Position position); + private native Position nativeGetPosition(); + private native TransitionOptions nativeGetPositionTransition(); + private native void nativeSetPositionTransition(long duration, long delay); + private native void nativeSetColor(String color); + private native String nativeGetColor(); + private native TransitionOptions nativeGetColorTransition(); + private native void nativeSetColorTransition(long duration, long delay); + private native void nativeSetIntensity(float intensity); + private native float nativeGetIntensity(); + private native TransitionOptions nativeGetIntensityTransition(); + private native void nativeSetIntensityTransition(long duration, long delay); } \ No newline at end of file diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Position.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Position.java index 215db03ad25..cd6218d3e26 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Position.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/Position.java @@ -18,7 +18,7 @@ public class Position { private float polarAngle; /** - * Creates a Position from a radial coordinate, an azimuthal angle & a polar angle. + * Creates a Position from a radial coordinate, an azimuthal angle and a polar angle. * * @param radialCoordinate the distance from the center of the base of an object to its light * @param azimuthalAngle the position of the light relative to 0° @@ -31,7 +31,7 @@ public Position(float radialCoordinate, float azimuthalAngle, float polarAngle) } /** - * Returns a Position from a radial coordinate, an azimuthal angle & a polar angle + * Returns a Position from a radial coordinate, an azimuthal angle and a polar angle * * @param radialCoordinate the radial coordinate * @param azimuthalAngle the azimuthal angle diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/light.java.ejs b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/light.java.ejs index 067efe1092a..80d927128d0 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/light.java.ejs +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/light/light.java.ejs @@ -17,7 +17,7 @@ import com.mapbox.mapboxsdk.style.layers.TransitionOptions; /** * The global light source. * - * @see The online documentation + * @see The online documentation */ @UiThread public class Light { diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/BitmapUtils.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/BitmapUtils.java index e3fc7657342..af3a79539fd 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/BitmapUtils.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/BitmapUtils.java @@ -5,8 +5,17 @@ import android.support.annotation.NonNull; import android.view.View; +/** + * Utility class for creating bitmaps + */ public class BitmapUtils { + /** + * Convert a view to a bitmap. + * + * @param view the view to convert + * @return the converted bitmap + */ public static Bitmap createBitmapFromView(@NonNull View view) { view.setDrawingCacheEnabled(true); view.setDrawingCacheQuality(View.DRAWING_CACHE_QUALITY_LOW); @@ -22,6 +31,13 @@ public static Bitmap createBitmapFromView(@NonNull View view) { return snapshot; } + /** + * Create a bitmap from a background and a foreground bitmap + * + * @param background The bitmap placed in the background + * @param foreground The bitmap placed in the foreground + * @return the merged bitmap + */ public static Bitmap mergeBitmap(@NonNull Bitmap background, @NonNull Bitmap foreground) { Bitmap result = Bitmap.createBitmap(background.getWidth(), background.getHeight(), background.getConfig()); Canvas canvas = new Canvas(result); diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java index 24c76243d96..14b18b00dc8 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/ColorUtils.java @@ -23,7 +23,7 @@ public class ColorUtils { /** - * Returns a color integer associated as primary color from a theme based on a {@link Context}. + * Returns a color integer associated as primary color from a theme based on a Context. * * @param context The context used to style the color attributes. * @return The primary color value of current theme in the form 0xAARRGGBB. @@ -37,7 +37,7 @@ public static int getPrimaryColor(@NonNull Context context) { } /** - * Returns a color integer associated as primary dark color from a theme based on a {@link Context}. + * Returns a color integer associated as primary dark color from a theme based on a Context. * * @param context The context used to style the color attributes. * @return The primary dark color value of current theme in the form 0xAARRGGBB. @@ -51,7 +51,7 @@ public static int getPrimaryDarkColor(@NonNull Context context) { } /** - * Returns a color integer associated as accent color from a theme based on a {@link Context}. + * Returns a color integer associated as accent color from a theme based on a Context. * * @param context The context used to style the color attributes. * @return The accent color value of current theme in the form 0xAARRGGBB. @@ -65,7 +65,7 @@ public static int getAccentColor(@NonNull Context context) { } /** - * Returns a color state list associated with a theme based on a {@link Context} + * Returns a color state list associated with a theme based on a Context. * * @param color The color used for tinting. * @return A ColorStateList object containing the primary color of a theme @@ -85,7 +85,7 @@ public static ColorStateList getSelector(@ColorInt int color) { } /** - * Set a color tint list to the {@link Drawable} of an {@link ImageView}. + * Set a color tint list to the Drawable of an ImageView. * * @param imageView The view to set the default tint list. * @param tintColor The color to tint. diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/MapFragmentUtils.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/MapFragmentUtils.java index f810d6231da..007880acd13 100644 --- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/MapFragmentUtils.java +++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/utils/MapFragmentUtils.java @@ -18,12 +18,25 @@ */ public class MapFragmentUtils { + /** + * Convert MapboxMapOptions to a bundle of fragment arguments. + * + * @param options The MapboxMapOptions to convert + * @return a bundle of converted fragment arguments + */ public static Bundle createFragmentArgs(MapboxMapOptions options) { Bundle bundle = new Bundle(); bundle.putParcelable(MapboxConstants.FRAG_ARG_MAPBOXMAPOPTIONS, options); return bundle; } + /** + * Convert a bundle of fragment arguments to MapboxMapOptions. + * + * @param context The context of the activity hosting the fragment + * @param args The fragment arguments + * @return converted MapboxMapOptions + */ public static MapboxMapOptions resolveArgs(Context context, Bundle args) { MapboxMapOptions options; if (args != null && args.containsKey(MapboxConstants.FRAG_ARG_MAPBOXMAPOPTIONS)) {