1 files changed, 99 insertions, 21 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/attribution/AttributionParser.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/attribution/AttributionParser.java
index 99100419c7..90bb23429f 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/attribution/AttributionParser.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/attribution/AttributionParser.java
@@ -8,35 +8,61 @@ import android.text.style.URLSpan;
 import java.util.LinkedHashSet;
 import java.util.Set;
 
+/**
+ * Responsible for parsing attribution data coming from Sources and MapSnapshot.
+ * <p>
+ * Exposes multiple configuration options to manipulate data being parsed.
+ * Use the Options object to build these configurations.
+ * </p>
+ */
 public class AttributionParser {
 
   private final Set<Attribution> attributions = new LinkedHashSet<>();
+  private final String attributionData;
+  private final boolean withImproveMap;
+  private final boolean withCopyrightSign;
+  private final boolean withTelemetryAttribution;
+  private final boolean withMapboxAttribution;
 
-  private String attributionDataString;
-  private boolean withImproveMap;
-  private boolean withCopyrightSign;
-  private boolean withTelemetryAttribution;
-  private boolean withMapboxAttribution;
-
-  AttributionParser(String attributionDataString, boolean withImproveMap, boolean withCopyrightSign,
+  AttributionParser(String attributionData, boolean withImproveMap, boolean withCopyrightSign,
                     boolean withTelemetryAttribution, boolean withMapboxAttribution) {
-    this.attributionDataString = attributionDataString;
+    this.attributionData = attributionData;
     this.withImproveMap = withImproveMap;
     this.withCopyrightSign = withCopyrightSign;
     this.withTelemetryAttribution = withTelemetryAttribution;
     this.withMapboxAttribution = withMapboxAttribution;
   }
 
+  /**
+   * Get parsed attributions.
+   *
+   * @return the attributions
+   */
   public Set<Attribution> getAttributions() {
     return attributions;
   }
 
-  public String getAttributionString() {
+  /**
+   * Get parsed attribution string.
+   *
+   * @return the parsed attribution string
+   */
+  public String createAttributionString() {
+    return createAttributionString(false);
+  }
+
+  /**
+   * Get parsed attribution string.
+   *
+   * @param shortenedOutput if attribution string should contain shortened output
+   * @return the parsed attribution string
+   */
+  public String createAttributionString(boolean shortenedOutput) {
     StringBuilder stringBuilder = new StringBuilder(withCopyrightSign ? "" : "© ");
     int counter = 0;
     for (Attribution attribution : attributions) {
       counter++;
-      stringBuilder.append(attribution.getTitle());
+      stringBuilder.append(!shortenedOutput ? attribution.getTitle() : attribution.getTitleAbbreviated());
       if (counter != attributions.size()) {
         stringBuilder.append(" / ");
       }
@@ -44,39 +70,76 @@ public class AttributionParser {
     return stringBuilder.toString();
   }
 
-  void parse() {
+  /**
+   * Main attribution for configuration
+   */
+  protected void parse() {
     parseAttributions();
     addAdditionalAttributions();
   }
 
+  /**
+   * Parse attributions
+   */
   private void parseAttributions() {
-    SpannableStringBuilder htmlBuilder = (SpannableStringBuilder) fromHtml(attributionDataString);
+    SpannableStringBuilder htmlBuilder = (SpannableStringBuilder) fromHtml(attributionData);
     URLSpan[] urlSpans = htmlBuilder.getSpans(0, htmlBuilder.length(), URLSpan.class);
     for (URLSpan urlSpan : urlSpans) {
       parseUrlSpan(htmlBuilder, urlSpan);
     }
   }
 
+  /**
+   * Parse an URLSpan containing an attribution.
+   *
+   * @param htmlBuilder the html builder
+   * @param urlSpan     the url span to be parsed
+   */
   private void parseUrlSpan(SpannableStringBuilder htmlBuilder, URLSpan urlSpan) {
     String url = urlSpan.getURL();
-    if (isUrlSpanValid(url)) {
-      String title = parseAnchorValue(htmlBuilder, urlSpan);
-      attributions.add(new Attribution(title, url));
+    if (isUrlValid(url)) {
+      String anchor = parseAnchorValue(htmlBuilder, urlSpan);
+      attributions.add(new Attribution(anchor, url));
     }
   }
 
-  private boolean isUrlSpanValid(String url) {
+  /**
+   * Invoked to validate if an url is valid to be included in the final attribution.
+   *
+   * @param url the url to be validated
+   * @return if the url is valid
+   */
+  private boolean isUrlValid(String url) {
     return isValidForImproveThisMap(url) && isValidForMapbox(url);
   }
 
+  /**
+   * Invoked to validate if an url is valid for the improve map configuration.
+   *
+   * @param url the url to be validated
+   * @return if the url is valid for improve this map
+   */
   private boolean isValidForImproveThisMap(String url) {
-    return withImproveMap || !url.equals("https://www.mapbox.com/map-feedback/");
+    return withImproveMap || !url.equals(Attribution.IMPROVE_MAP_URL);
   }
 
+  /**
+   * Invoked to validate if an url is valid for the Mapbox configuration.
+   *
+   * @param url the url to be validated
+   * @return if the url is valid for Mapbox
+   */
   private boolean isValidForMapbox(String url) {
-    return withMapboxAttribution || !url.equals("https://www.mapbox.com/about/maps/");
+    return withMapboxAttribution || !url.equals(Attribution.MAPBOX_URL);
   }
 
+  /**
+   * Parse the attribution by parsing the anchor value of html href tag.
+   *
+   * @param htmlBuilder the html builder
+   * @param urlSpan     the current urlSpan
+   * @return the parsed anchor value
+   */
   private String parseAnchorValue(SpannableStringBuilder htmlBuilder, URLSpan urlSpan) {
     int start = htmlBuilder.getSpanStart(urlSpan);
     int end = htmlBuilder.getSpanEnd(urlSpan);
@@ -86,6 +149,12 @@ public class AttributionParser {
     return stripCopyright(String.valueOf(charKey));
   }
 
+  /**
+   * Utility to strip the copyright sign from an attribution
+   *
+   * @param anchor the attribution string to strip
+   * @return the stripped attribution string without the copyright sign
+   */
   private String stripCopyright(String anchor) {
     if (!withCopyrightSign && anchor.startsWith("© ")) {
       anchor = anchor.substring(2, anchor.length());
@@ -93,11 +162,12 @@ public class AttributionParser {
     return anchor;
   }
 
+  /**
+   * Invoked to manually add attributions
+   */
   private void addAdditionalAttributions() {
     if (withTelemetryAttribution) {
-      String telemetryKey = "Telemetry Settings";
-      String telemetryLink = "https://www.mapbox.com/telemetry/";
-      attributions.add(new Attribution(telemetryKey, telemetryLink));
+      attributions.add(new Attribution(Attribution.TELEMETRY, Attribution.TELEMETRY_URL));
     }
   }
 
@@ -117,6 +187,14 @@ public class AttributionParser {
     return result;
   }
 
+  /**
+   * Builder to configure using an AttributionParser.
+   * <p>
+   * AttributionData, set with {@link #withAttributionData(String...)}, is the only required property to build
+   * the underlying AttributionParser. Other properties include trimming the copyright sign, adding telemetry
+   * attribution or hiding attribution as improve this map and Mapbox.
+   * </p>
+   */
   public static class Options {
     private boolean withImproveMap = true;
     private boolean withCopyrightSign = true;