[android] #5880 - javadoc cleanup part one

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/MapboxAccountManager.java

@@ -60,7 +60,7 @@ public static MapboxAccountManager getInstance() {
     }
 
     /**
-     * Access Token for this application
+     * Access Token for this application.
      *
      * @return Mapbox Access Token
      */
@@ -69,10 +69,10 @@ public String getAccessToken() {
     }
 
     /**
-     * Runtime validation of Access Token
+     * Runtime validation of Access Token.
      *
      * @param accessToken Access Token to check
-     * @throws InvalidAccessTokenException
+     * @throws InvalidAccessTokenException the exception thrown
      */
     public static void validateAccessToken(String accessToken) throws InvalidAccessTokenException {
         if (TextUtils.isEmpty(accessToken) || (!accessToken.toLowerCase(MapboxConstants.MAPBOX_LOCALE).startsWith("pk.") && !accessToken.toLowerCase(MapboxConstants.MAPBOX_LOCALE).startsWith("sk."))) {

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Annotation.java

@@ -34,6 +34,8 @@ protected Annotation() {
      * </p>
      * This ID is unique for a MapView instance and is suitable for associating your own extra
      * data with.
+     *
+     * @return the assigned id
      */
     public long getId() {
         return id;
@@ -48,36 +50,42 @@ public void remove() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param id the assigned id
      */
     public void setId(long id) {
         this.id = id;
     }
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param mapboxMap the hosting mapbox map
      */
     public void setMapboxMap(MapboxMap mapboxMap) {
         this.mapboxMap = mapboxMap;
     }
 
     /**
-     * Gets the associated MapboxMap
+     * Gets the hosting mapbox map.
      *
-     * @return The MapboxMap
+     * @return the MapboxMap
      */
     protected MapboxMap getMapboxMap() {
         return mapboxMap;
     }
 
     /**
      * Don not use this method.  Used internally by the SDK.
+     *
+     * @param mapView the hosting map view
      */
     public void setMapView(MapView mapView) {
         this.mapView = mapView;
     }
 
     /**
-     * Gets the associated MapView
+     * Gets the hosting map view.
      *
      * @return The MapView
      */

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/Marker.java

@@ -3,6 +3,7 @@
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.view.View;
+
 import com.mapbox.mapboxsdk.R;
 import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.maps.MapView;
@@ -41,7 +42,7 @@ public Marker(BaseMarkerOptions baseMarkerOptions) {
         title = baseMarkerOptions.title;
     }
 
-    Marker(BaseMarkerViewOptions baseMarkerViewOptions){
+    Marker(BaseMarkerViewOptions baseMarkerViewOptions) {
         position = baseMarkerViewOptions.position;
         snippet = baseMarkerViewOptions.snippet;
         icon = baseMarkerViewOptions.icon;
@@ -72,6 +73,8 @@ public void hideInfoWindow() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @return true if the infoWindow is shown
      */
     public boolean isInfoWindowShown() {
         return infoWindowShown;
@@ -126,7 +129,7 @@ public InfoWindow getInfoWindow() {
      * Update only for default Marker's InfoWindow content for Title and Snippet
      */
     private void refreshInfoWindowContent() {
-        if (isInfoWindowShown() && mapView != null  && mapboxMap != null && mapboxMap.getInfoWindowAdapter() == null) {
+        if (isInfoWindowShown() && mapView != null && mapboxMap != null && mapboxMap.getInfoWindowAdapter() == null) {
             InfoWindow infoWindow = getInfoWindow(mapView);
             if (mapView.getContext() != null) {
                 infoWindow.adaptDefaultMarker(this, mapboxMap, mapView);
@@ -140,6 +143,10 @@ private void refreshInfoWindowContent() {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param mapboxMap the hosting mapbox map
+     * @param mapView   the hosting map view
+     * @return the info window that was shown
      */
     public InfoWindow showInfoWindow(@NonNull MapboxMap mapboxMap, @NonNull MapView mapView) {
         setMapboxMap(mapboxMap);
@@ -177,13 +184,17 @@ private InfoWindow getInfoWindow(@NonNull MapView mapView) {
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param topOffsetPixels the top offset pixels.
      */
     public void setTopOffsetPixels(int topOffsetPixels) {
         this.topOffsetPixels = topOffsetPixels;
     }
 
     /**
      * Do not use this method. Used internally by the SDK.
+     *
+     * @param rightOffsetPixels the right offset pixels.
      */
     public void setRightOffsetPixels(int rightOffsetPixels) {
         this.rightOffsetPixels = rightOffsetPixels;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/annotations/MarkerViewManager.java

@@ -156,7 +156,9 @@ public void setTilt(float tilt) {
     }
 
     /**
+     * Update and invalidate the MarkerView icon.
      *
+     * @param markerView the marker view to updates
      */
     public void updateIcon(@NonNull MarkerView markerView) {
         View convertView = markerViewMap.get(markerView);

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/camera/CameraPosition.java

@@ -137,7 +137,7 @@ public Builder() {
         /**
          * Creates a builder for building CameraPosition objects using radiants.
          *
-         * @param isRadiant
+         * @param isRadiant true if heading is in radiants
          */
         public Builder(boolean isRadiant) {
             this.isRadiant = isRadiant;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/geometry/ProjectedMeters.java

@@ -27,10 +27,10 @@ public ProjectedMeters[] newArray(int size) {
     private double easting;
 
     /**
-     * Creates a ProjectedMeters based on projected meters in north and east direction
+     * Creates a ProjectedMeters based on projected meters in north and east direction.
      *
-     * @param northing
-     * @param easting
+     * @param northing the northing in meters
+     * @param easting  the easting in meters
      */
     public ProjectedMeters(double northing, double easting) {
         this.northing = northing;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java

@@ -881,8 +881,8 @@ public String getStyleUrl() {
      * DEPRECATED @see MapboxAccountManager#start(String)
      * </p>
      * <p>
-     * <p>
      * Sets the current Mapbox access token used to load map styles and tiles.
+     * </p>
      * <p>
      * You must set a valid access token before you call {@link MapView#onCreate(Bundle)}
      * or an exception will be thrown.

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMap.java

@@ -1908,7 +1908,6 @@ public MarkerViewAdapter(Context context) {
         /**
          * Called when an MarkerView is removed from the MapView or the View object is going to be reused.
          * <p>
-         * <p>
          * This method should be used to reset an animated view back to it's original state for view reuse.
          * </p>
          * <p>
@@ -1990,8 +1989,9 @@ public final void releaseView(View view) {
 
     /**
      * Interface definition for a callback to be invoked when the user clicks on a MarkerView.
-     *
-     * @see MarkerViewManager#setOnMarkerViewClickListener(OnMarkerViewClickListener)
+     * </p>
+     * {@link MarkerViewManager#setOnMarkerViewClickListener(OnMarkerViewClickListener)}
+     * </p>
      */
     public interface OnMarkerViewClickListener {
 

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapboxMapOptions.java

@@ -124,11 +124,11 @@ private MapboxMapOptions(Parcel in) {
     }
 
     /**
-     * Creates a GoogleMapsOptions from the attribute set
+     * Creates a MapboxMapsOptions from the attribute set.s
      *
      * @param context Context related to a map view.
      * @param attrs   Attributeset containing configuration
-     * @return
+     * @return the MapboxMapOptions created from attributes
      */
     public static MapboxMapOptions createFromAttributes(@NonNull Context context, @Nullable AttributeSet attrs) {
         MapboxMapOptions mapboxMapOptions = new MapboxMapOptions();

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/UiSettings.java

@@ -8,8 +8,6 @@
 import android.view.Gravity;
 import android.view.View;
 
-import com.mapbox.mapboxsdk.maps.widgets.MyLocationViewSettings;
-
 /**
  * Settings for the user interface of a MapboxMap. To obtain this interface, call getUiSettings().
  */
@@ -492,7 +490,7 @@ public boolean isZoomControlsEnabled() {
     /**
      * Gets whether the markers are automatically deselected (and therefore, their infowindows
      * closed) when a map tap is detected.
-
+     *
      * @return If true, markers are deselected on a map tap.
      */
     public boolean isDeselectMarkersOnTap() {
@@ -503,7 +501,7 @@ public boolean isDeselectMarkersOnTap() {
      * Sets whether the markers are automatically deselected (and therefore, their infowindows
      * closed) when a map tap is detected.
      *
-     * @param deselectMarkersOnTap
+     * @param deselectMarkersOnTap determines if markers should be deslected on tap
      */
     public void setDeselectMarkersOnTap(boolean deselectMarkersOnTap) {
         this.deselectMarkersOnTap = deselectMarkersOnTap;
@@ -580,7 +578,7 @@ public void setFocalPoint(@Nullable PointF focalPoint) {
     /**
      * Returns the gesture focal point
      *
-     * @return  The focal point
+     * @return The focal point
      */
     public PointF getFocalPoint() {
         return focalPoint;

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/offline/OfflineManager.java

@@ -55,16 +55,16 @@ public class OfflineManager {
      */
     public interface ListOfflineRegionsCallback {
         /**
-         * Receives the list of offline regions
+         * Receives the list of offline regions.
          *
-         * @param offlineRegions
+         * @param offlineRegions the offline region array
          */
         void onList(OfflineRegion[] offlineRegions);
 
         /**
-         * Receives the error message
+         * Receives the error message.
          *
-         * @param error
+         * @param error the error message
          */
         void onError(String error);
     }
@@ -75,16 +75,16 @@ public interface ListOfflineRegionsCallback {
      */
     public interface CreateOfflineRegionCallback {
         /**
-         * Receives the newly created offline region
+         * Receives the newly created offline region.
          *
-         * @param offlineRegion
+         * @param offlineRegion the offline region to create
          */
         void onCreate(OfflineRegion offlineRegion);
 
         /**
-         * Receives the error message
+         * Receives the error message.
          *
-         * @param error
+         * @param error the error message to be shown
          */
         void onError(String error);
     }
@@ -149,6 +149,8 @@ public static String getDatabasePath(Context context) {
      * <p>
      * Code from https://developer.android.com/guide/topics/data/data-storage.html#filesExternal
      * </p>
+     *
+     * @return true if external storage is readable
      */
     public static boolean isExternalStorageReadable() {
         String state = Environment.getExternalStorageState();
@@ -193,7 +195,7 @@ public static synchronized OfflineManager getInstance(Context context) {
     /**
      * Access token getter/setter
      *
-     * @param accessToken
+     * @param accessToken the accessToken to be used by the offline manager.
      * @deprecated As of release 4.1.0, replaced by {@link MapboxAccountManager#start(Context, String)} ()}
      */
     @Deprecated
@@ -226,6 +228,8 @@ private Handler getHandler() {
      * The query will be executed asynchronously and the results passed to the given
      * callback on the main thread.
      * </p>
+     *
+     * @param callback the callback to be invoked
      */
     public void listOfflineRegions(@NonNull final ListOfflineRegionsCallback callback) {
         listOfflineRegions(mDefaultFileSourcePtr, new ListOfflineRegionsCallback() {
@@ -262,6 +266,10 @@ public void run() {
      * downloading resources, call `OfflineRegion.setDownloadState(DownloadState.STATE_ACTIVE)`,
      * optionally registering an `OfflineRegionObserver` beforehand.
      * </p>
+     *
+     * @param definition the offline region definition
+     * @param metadata   the metadata in bytes
+     * @param callback   the callback to be invoked
      */
     public void createOfflineRegion(
             @NonNull OfflineRegionDefinition definition,