[all] - rename functions to include cluster

8 files changed, 65 insertions, 33 deletions

diff --git a/include/mbgl/style/sources/geojson_source.hpp b/include/mbgl/style/sources/geojson_source.hpp
index 36cc9bb4bb..f49863b565 100644
--- a/include/mbgl/style/sources/geojson_source.hpp
+++ b/include/mbgl/style/sources/geojson_source.hpp
@@ -35,8 +35,8 @@ public:
     void setGeoJSON(const GeoJSON&);
     optional<std::string> getURL() const;
 
-    mapbox::geometry::feature_collection<double> getChildren(const std::uint32_t) const;
-    mapbox::geometry::feature_collection<double> getLeaves(const std::uint32_t, const std::uint32_t, const std::uint32_t) const;
+    mapbox::geometry::feature_collection<double> getClusterChildren(const std::uint32_t) const;
+    mapbox::geometry::feature_collection<double> getClusterLeaves(const std::uint32_t, const std::uint32_t = 10U, const std::uint32_t = 0U) const;
     std::uint8_t getClusterExpansionZoom(std::uint32_t) const;
 
     class Impl;
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
index 1d54545b92..14232bd8a6 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/style/sources/GeoJsonSource.java
@@ -273,20 +273,51 @@ public class GeoJsonSource extends Source {
     return features != null ? Arrays.asList(features) : new ArrayList<>();
   }
 
+  /**
+   * Returns the children of a cluster (on the next zoom level) given its id (cluster_id value from feature properties).
+   * <p>
+   * Requires configuring this source as a cluster by calling {@link GeoJsonOptions#withCluster(boolean)}.
+   * </p>
+   *
+   * @param clusterId cluster_id value from feature properties
+   * @return a list of features for the underlying children
+   */
   @NonNull
-  public List<Feature> getChildren(long clusterId) {
+  public List<Feature> getClusterChildren(long clusterId) {
     checkThread();
-    Feature[] features = nativeGetChildren(clusterId);
+    Feature[] features = nativeGetClusterChildren(clusterId);
     return features != null ? Arrays.asList(features) : new ArrayList<>();
   }
 
+  /**
+   * Returns all the points of a cluster (given its cluster_id), with pagination support: limit is the number of points
+   * to return (set to Infinity for all points), and offset is the amount of points to skip (for pagination).
+   * <p>
+   * Requires configuring this source as a cluster by calling {@link GeoJsonOptions#withCluster(boolean)}.
+   * </p>
+   *
+   * @param clusterId cluster_id value from feature properties
+   * @param limit  limit is the number of points to return
+   * @param offset  offset is the amount of points to skip (for pagination)
+   * @return a list of features for the underlying leaves
+   */
   @NonNull
-  public List<Feature> getLeaves(long clusterId, long limit, long offset) {
+  public List<Feature> getClusterLeaves(long clusterId, long limit, long offset) {
     checkThread();
-    Feature[] features = nativeGetLeaves(clusterId, limit, offset);
+    Feature[] features = nativeGetClusterLeaves(clusterId, limit, offset);
     return features != null ? Arrays.asList(features) : new ArrayList<>();
   }
 
+  /**
+   * Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature)
+   * given the cluster's cluster_id (cluster_id value from feature properties).
+   * <p>
+   * Requires configuring this source as a cluster by calling {@link GeoJsonOptions#withCluster(boolean)}.
+   * </p>
+   *
+   * @param clusterId cluster_id value from feature properties
+   * @return the zoom on which the cluster expands into several children
+   */
   public double getClusterExpansionZoom(long clusterId) {
     checkThread();
     return nativeGetClusterExpansionZoom(clusterId);
@@ -319,10 +350,10 @@ public class GeoJsonSource extends Source {
   private native Feature[] querySourceFeatures(Object[] filter);
 
   @Keep
-  private native Feature[] nativeGetChildren(long clusterId);
+  private native Feature[] nativeGetClusterChildren(long clusterId);
 
   @Keep
-  private native Feature[]  nativeGetLeaves(long clusterId, long limit, long offset);
+  private native Feature[] nativeGetClusterLeaves(long clusterId, long limit, long offset);
 
   @Keep
   private native double nativeGetClusterExpansionZoom(long clusterId);
diff --git a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/style/GeoJsonClusteringActivity.java b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/style/GeoJsonClusteringActivity.java
index d857d0a798..ca3fb8b368 100644
--- a/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/style/GeoJsonClusteringActivity.java
+++ b/platform/android/MapboxGLAndroidSDKTestApp/src/main/java/com/mapbox/mapboxsdk/testapp/activity/style/GeoJsonClusteringActivity.java
@@ -240,7 +240,7 @@ public class GeoJsonClusteringActivity extends AppCompatActivity {
           "Cluster= (id=%s) with %s points, cluster will expand at zoom %s",
           clusterId, pointCount, expansionZoom
         );
-        recursiveLoopClusterFeatures(source.getLeaves(clusterId, 10, 0));
+        recursiveLoopClusterFeatures(source.getClusterLeaves(clusterId, 10, 0));
       } else {
         Timber.e("Point data: %s", feature.toJson());
       }
diff --git a/platform/android/src/style/sources/geojson_source.cpp b/platform/android/src/style/sources/geojson_source.cpp
index 605b0c6e62..3f2afd7ae6 100644
--- a/platform/android/src/style/sources/geojson_source.cpp
+++ b/platform/android/src/style/sources/geojson_source.cpp
@@ -108,19 +108,19 @@ namespace android {
         return Feature::convert(env, features);
     }
 
-    jni::Local<jni::Array<jni::Object<geojson::Feature>>> GeoJSONSource::getChildren(jni::JNIEnv& env, jni::jlong clusterId) {
+    jni::Local<jni::Array<jni::Object<geojson::Feature>>> GeoJSONSource::getClusterChildren(jni::JNIEnv& env, jni::jlong clusterId) {
         using namespace mbgl::android::conversion;
         using namespace mbgl::android::geojson;
 
-        std::vector<mbgl::Feature> features = source.as<mbgl::style::GeoJSONSource>()->GeoJSONSource::getChildren(clusterId);
+        std::vector<mbgl::Feature> features = source.as<mbgl::style::GeoJSONSource>()->GeoJSONSource::getClusterChildren(clusterId);
         return Feature::convert(env, features);
     }
 
-    jni::Local<jni::Array<jni::Object<geojson::Feature>>> GeoJSONSource::getLeaves(jni::JNIEnv& env, jni::jlong clusterId, jni::jlong limit, jni::jlong offset) {
+    jni::Local<jni::Array<jni::Object<geojson::Feature>>> GeoJSONSource::getClusterLeaves(jni::JNIEnv& env, jni::jlong clusterId, jni::jlong limit, jni::jlong offset) {
         using namespace mbgl::android::conversion;
         using namespace mbgl::android::geojson;
 
-        std::vector<mbgl::Feature> features = source.as<mbgl::style::GeoJSONSource>()->GeoJSONSource::getLeaves(clusterId, limit, offset);
+        std::vector<mbgl::Feature> features = source.as<mbgl::style::GeoJSONSource>()->GeoJSONSource::getClusterLeaves(clusterId, limit, offset);
         return Feature::convert(env, features);
     }
 
@@ -197,8 +197,8 @@ namespace android {
             METHOD(&GeoJSONSource::setURL, "nativeSetUrl"),
             METHOD(&GeoJSONSource::getURL, "nativeGetUrl"),
             METHOD(&GeoJSONSource::querySourceFeatures, "querySourceFeatures"),
-            METHOD(&GeoJSONSource::getLeaves, "nativeGetLeaves"),
-            METHOD(&GeoJSONSource::getChildren, "nativeGetChildren"),
+            METHOD(&GeoJSONSource::getClusterLeaves, "nativeGetClusterLeaves"),
+            METHOD(&GeoJSONSource::getClusterChildren, "nativeGetClusterChildren"),
             METHOD(&GeoJSONSource::getClusterExpansionZoom, "nativeGetClusterExpansionZoom")
         );
     }
diff --git a/platform/android/src/style/sources/geojson_source.hpp b/platform/android/src/style/sources/geojson_source.hpp
index 9f7729ff7f..3a949a234e 100644
--- a/platform/android/src/style/sources/geojson_source.hpp
+++ b/platform/android/src/style/sources/geojson_source.hpp
@@ -51,9 +51,9 @@ private:
 
     jni::Local<jni::String> getURL(jni::JNIEnv&);
 
-    jni::Local<jni::Array<jni::Object<geojson::Feature>>> getChildren(jni::JNIEnv&, jni::jlong);
+    jni::Local<jni::Array<jni::Object<geojson::Feature>>> getClusterChildren(jni::JNIEnv &, jni::jlong);
 
-    jni::Local<jni::Array<jni::Object<geojson::Feature>>> getLeaves(jni::JNIEnv&, jni::jlong, jni::jlong, jni::jlong);
+    jni::Local<jni::Array<jni::Object<geojson::Feature>>> getClusterLeaves(jni::JNIEnv &, jni::jlong, jni::jlong, jni::jlong);
 
     jni::jdouble getClusterExpansionZoom(jni::JNIEnv&, jni::jlong);
 
diff --git a/src/mbgl/style/sources/geojson_source.cpp b/src/mbgl/style/sources/geojson_source.cpp
index 665cc9c0dc..79ab6b33e5 100644
--- a/src/mbgl/style/sources/geojson_source.cpp
+++ b/src/mbgl/style/sources/geojson_source.cpp
@@ -40,14 +40,14 @@ optional<std::string> GeoJSONSource::getURL() const {
     return url;
 }
 
-mapbox::geometry::feature_collection<double> GeoJSONSource::getChildren(const std::uint32_t cluster_id) const {
-    return impl().getData()->getChildren(cluster_id);
+mapbox::geometry::feature_collection<double> GeoJSONSource::getClusterChildren(const std::uint32_t cluster_id) const {
+    return impl().getData()->getClusterChildren(cluster_id);
 }
 
-mapbox::geometry::feature_collection<double> GeoJSONSource::getLeaves(const std::uint32_t cluster_id,
-                                                           const std::uint32_t limit = 10,
-                                                           const std::uint32_t offset = 0) const{
-    return impl().getData()->getLeaves(cluster_id, limit, offset);
+mapbox::geometry::feature_collection<double> GeoJSONSource::getClusterLeaves(const std::uint32_t cluster_id,
+                                                           const std::uint32_t limit,
+                                                           const std::uint32_t offset) const {
+    return impl().getData()->getClusterLeaves(cluster_id, limit, offset);
 }
 
 std::uint8_t GeoJSONSource::getClusterExpansionZoom(std::uint32_t cluster_id) const {
diff --git a/src/mbgl/style/sources/geojson_source_impl.cpp b/src/mbgl/style/sources/geojson_source_impl.cpp
index fd7e6b50f6..84f462e410 100644
--- a/src/mbgl/style/sources/geojson_source_impl.cpp
+++ b/src/mbgl/style/sources/geojson_source_impl.cpp
@@ -21,17 +21,18 @@ public:
         return impl.getTile(tileID.z, tileID.x, tileID.y).features;
     }
 
-    mapbox::geometry::feature_collection<double> getChildren(const std::uint32_t) final {
+    mapbox::geometry::feature_collection<double> getClusterChildren(const std::uint32_t) final {
+        // no-op, SuperclusterData only
         return {};
     }
 
-    mapbox::geometry::feature_collection<double> getLeaves(const std::uint32_t,
-                                                           const std::uint32_t,
-                                                           const std::uint32_t) final {
+    mapbox::geometry::feature_collection<double> getClusterLeaves(const std::uint32_t, const std::uint32_t, const std::uint32_t) final {
+        // no-op, SuperclusterData only
         return {};
     }
 
     std::uint8_t getClusterExpansionZoom(std::uint32_t) final {
+        // no-op, SuperclusterData only
         return 0;
     }
 
@@ -49,13 +50,13 @@ public:
         return impl.getTile(tileID.z, tileID.x, tileID.y);
     }
 
-    mapbox::geometry::feature_collection<double> getChildren(const std::uint32_t cluster_id) final {
+    mapbox::geometry::feature_collection<double> getClusterChildren(const std::uint32_t cluster_id) final {
         return impl.getChildren(cluster_id);
     }
 
-    mapbox::geometry::feature_collection<double> getLeaves(const std::uint32_t cluster_id,
-                                                           const std::uint32_t limit = 10,
-                                                           const std::uint32_t offset = 0) final {
+    mapbox::geometry::feature_collection<double> getClusterLeaves(const std::uint32_t cluster_id,
+                                                           const std::uint32_t limit,
+                                                           const std::uint32_t offset) final {
         return impl.getLeaves(cluster_id, limit, offset);
     }
 
diff --git a/src/mbgl/style/sources/geojson_source_impl.hpp b/src/mbgl/style/sources/geojson_source_impl.hpp
index f12e16ccb2..8fa40c78e9 100644
--- a/src/mbgl/style/sources/geojson_source_impl.hpp
+++ b/src/mbgl/style/sources/geojson_source_impl.hpp
@@ -17,8 +17,8 @@ public:
     virtual mapbox::geometry::feature_collection<int16_t> getTile(const CanonicalTileID&) = 0;
 
     // SuperclusterData
-    virtual mapbox::geometry::feature_collection<double> getChildren(const std::uint32_t) = 0;
-    virtual mapbox::geometry::feature_collection<double> getLeaves(const std::uint32_t, const std::uint32_t,
+    virtual mapbox::geometry::feature_collection<double> getClusterChildren(const std::uint32_t) = 0;
+    virtual mapbox::geometry::feature_collection<double> getClusterLeaves(const std::uint32_t, const std::uint32_t,
                                                                    const std::uint32_t) = 0;
     virtual std::uint8_t getClusterExpansionZoom(std::uint32_t) = 0;
 };