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

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.
  * <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>
  */
@@ -97,6 +96,8 @@ private static void validateAccessToken() throws MapboxConfigurationException {
 
   /**
    * Application context
+   *
+   * @return the application context
    */
   public static Context getApplicationContext() {
     return INSTANCE.context;

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,85 +96,173 @@ 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;
     initPadding();
     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;
     initPadding();
     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;
     initPadding();
     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;
     initPadding();
     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;
     initPadding();
     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();

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

@@ -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
@@ -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,23 +152,22 @@ 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);
     return fromBitmap(bitmap);
   }
 
   /**
-   * 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>
    */
@@ -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);