[android] javadoc - inter-link style properties properly

1 files changed, 117 insertions, 3 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
index a0d065a6e9..4d9791b125 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/layers/Filter.java
@@ -1,16 +1,18 @@
 package com.mapbox.mapboxsdk.style.layers;
 
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.Collections;
 
 /**
- * Utility to build filter expressions more easily:
+ * Utility to build filter expressions more easily.
  *
- * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#types-filter">Style spec</a>
+ * @see <a href="https://www.mapbox.com/mapbox-gl-style-spec/#types-filter">The online documentation</a>
  */
 public class Filter {
 
+    /**
+     * Base {@link Filter} statement. Subclassed to provide concrete statements.
+     */
     public abstract static class Statement {
         protected final String operator;
 
@@ -18,13 +20,26 @@ public class Filter {
             this.operator = operator;
         }
 
+        /**
+         * Generate a raw array representation of the filter
+         *
+         * @return the filter represented as an array
+         */
         public abstract Object[] toArray();
     }
 
+    /**
+     * Represents a {@link Filter} statement. Can be unary (eg `has()`, etc) or take any number of values.
+     */
     public static class SimpleStatement extends Statement {
         private final String key;
         private final Object[] values;
 
+        /**
+         * @param operator the operator (eg `=`, etc)
+         * @param key      the property key
+         * @param values   the values to operate on, if any
+         */
         public SimpleStatement(String operator, String key, Object... values) {
             super(operator);
             this.key = key;
@@ -32,6 +47,9 @@ public class Filter {
         }
 
 
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public Object[] toArray() {
             ArrayList<Object> array = new ArrayList<>(2 + values.length);
@@ -42,14 +60,24 @@ public class Filter {
         }
     }
 
+    /**
+     * Represents a collection of {@link Statement}s with an operator that describes their relationship
+     */
     public static class CompoundStatement extends Statement {
         private final Statement[] statements;
 
+        /**
+         * @param operator   the relationship operator
+         * @param statements the statements to compound
+         */
         public CompoundStatement(String operator, Statement... statements) {
             super(operator);
             this.statements = statements;
         }
 
+        /**
+         * {@inheritDoc}
+         */
         @Override
         public Object[] toArray() {
             ArrayList<Object> array = new ArrayList<>(1 + statements.length);
@@ -61,54 +89,140 @@ public class Filter {
         }
     }
 
+    /**
+     * Groups a collection of statements in an 'all' relationship
+     *
+     * @param statements the collection of statements
+     * @return the statements compounded
+     */
     public static Statement all(Statement... statements) {
         return new CompoundStatement("all", statements);
     }
 
+    /**
+     * Groups a collection of statements in an 'any' relationship
+     *
+     * @param statements the collection of statements
+     * @return the statements compounded
+     */
     public static Statement any(Statement... statements) {
         return new CompoundStatement("any", statements);
     }
 
+    /**
+     * Groups a collection of statements in an 'none' relationship
+     *
+     * @param statements the collection of statements
+     * @return the statements compounded
+     */
     public static Statement none(Statement... statements) {
         return new CompoundStatement("none", statements);
     }
 
+    /**
+     * Check the property's existence
+     *
+     * @param key the property key
+     * @return the statement
+     */
     public static Statement has(String key) {
         return new SimpleStatement("has", key);
     }
 
+    /**
+     * Check the property's existence, negated
+     *
+     * @param key the property key
+     * @return the statement
+     */
     public static Statement notHas(String key) {
         return new SimpleStatement("!has", key);
     }
 
+    /**
+     * Check the property equals the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement eq(String key, Object value) {
         return new SimpleStatement("==", key, value);
     }
 
+    /**
+     * Check the property does not equals the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement neq(String key, Object value) {
         return new SimpleStatement("!=", key, value);
     }
 
+    /**
+     * Check the property exceeds the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement gt(String key, Object value) {
         return new SimpleStatement(">", key, value);
     }
 
+    /**
+     * Check the property exceeds or equals the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement gte(String key, Object value) {
         return new SimpleStatement(">=", key, value);
     }
 
+    /**
+     * Check the property does not exceeds the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement lt(String key, Object value) {
         return new SimpleStatement("<", key, value);
     }
 
+    /**
+     * Check the property equals or does not exceeds the given value
+     *
+     * @param key   the property key
+     * @param value the value to check against
+     * @return the statement
+     */
     public static Statement lte(String key, Object value) {
         return new SimpleStatement("<=", key, value);
     }
 
+    /**
+     * Check the property is within the given set
+     *
+     * @param key    the property key
+     * @param values the set of values to check against
+     * @return the statement
+     */
     public static Statement in(String key, Object... values) {
         return new SimpleStatement("in", key, values);
     }
 
+    /**
+     * Check the property is not within the given set
+     *
+     * @param key    the property key
+     * @param values the set of values to check against
+     * @return the statement
+     */
     public static Statement notIn(String key, Object... values) {
         return new SimpleStatement("!in", key, values);
     }