Skip to content
This repository has been archived by the owner on Aug 8, 2023. It is now read-only.

Commit

Permalink
[android] - revisit public API javadoc
Browse files Browse the repository at this point in the history
  • Loading branch information
tobrun committed Jun 14, 2017
1 parent 7bfcce0 commit 670c08a
Show file tree
Hide file tree
Showing 32 changed files with 589 additions and 212 deletions.
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
package com.mapbox.mapboxsdk;

import android.app.Application;
import android.content.Context;
import android.net.ConnectivityManager;
import android.net.NetworkInfo;
Expand All @@ -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.
* <p>
* 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.
* </p>
*/
Expand Down Expand Up @@ -97,6 +96,8 @@ private static void validateAccessToken() throws MapboxConfigurationException {

/**
* Application context
*
* @return the application context
*/
public static Context getApplicationContext() {
return INSTANCE.context;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
/**
* Factory for creating Icons from bitmap images.
* <p>
* {@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}.
* </p>
*
* @see Icon
Expand All @@ -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());
Expand Down Expand Up @@ -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) {
Expand All @@ -85,10 +91,10 @@ public Icon fromBitmap(@NonNull Bitmap bitmap) {
}

/**
* Create an {@link Icon} using the resource ID of a Bitmap image.
* Create 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);
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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;
Expand All @@ -146,10 +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
* @return The Icon that was loaded from the absolute path or null if failed to
* load.
*/
public Icon fromPath(@NonNull String absolutePath) {
Expand All @@ -158,11 +164,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 <a href="https://developer.android.com/guide/topics/data/data-storage.html#filesInternal">
* Using the Internal Storage</a>
*/
Expand All @@ -177,12 +183,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);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -532,10 +532,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;
Expand All @@ -560,9 +561,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;
Expand Down Expand Up @@ -612,7 +613,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<MarkerView> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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;
Expand All @@ -252,48 +253,53 @@ 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;
return this;
}

/**
* Set the tilt in degrees
* Set the tilt of the camera in degrees
* <p>
* value is clamped to 0 and 60.
* value is clamped to {@link MapboxConstants#MINIMUM_TILT} and {@link MapboxConstants#MAXIMUM_TILT}.
* </p>
*
* @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
* <p>
* Zoom ranges from {@link MapboxConstants#MINIMUM_ZOOM} to {@link MapboxConstants#MAXIMUM_ZOOM}
* </p>
*
* @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);
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,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
*/
CameraPosition getCameraPosition(@NonNull MapboxMap mapboxMap);

}
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
* <p>
* These modes visualise the user direction by extracting the direction from either sensor or location data.
* </p>
* <p>
* Required to enable showing the user location first through {@link MapboxMap#setMyLocationEnabled(boolean)}.
* </p>
*
* @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 {
}
Expand Down
Loading

0 comments on commit 670c08a

Please sign in to comment.