Update feature pick listener docs (#401)

* update feature pick listener docs * update doc * add marker interface docs
mapzen · Jun 7, 2017 · 6c1a963 · 6c1a963
1 parent 8845854
commit 6c1a963
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 3 deletions.
diff --git a/core/src/main/java/com/mapzen/android/graphics/FeaturePickListener.java b/core/src/main/java/com/mapzen/android/graphics/FeaturePickListener.java
@@ -7,7 +7,16 @@
  */
 public interface FeaturePickListener {
   /**
-   * Receive information about features found in a call to {@link #pickFeature(float, float)}.
+   * Receive information about features found in a call to
+   * {@link com.mapzen.tangram.MapController#pickFeature(float, float)}. Note that a feature refers
+   * to a {@link com.mapzen.android.graphics.model.Polygon} or
+   * {@link com.mapzen.android.graphics.model.Polyline} and is any
+   * {@link com.mapzen.tangram.MapData} drawn using non-point style. It does not include
+   * {@link com.mapzen.android.graphics.model.Marker}s or points, including MapData drawn using
+   * points style. To receive pick information for
+   * {@link com.mapzen.android.graphics.model.Marker}s, use the {@link MarkerPickListener} interface
+   * and to receive pick information for points, including MapData drawn using points style, use the
+   * {@link FeaturePickListener} interface.
    *
    * @param properties A mapping of string keys to string or number values
    * @param positionX The horizontal screen coordinate of the center of the feature

diff --git a/core/src/main/java/com/mapzen/android/graphics/LabelPickListener.java b/core/src/main/java/com/mapzen/android/graphics/LabelPickListener.java
@@ -9,7 +9,17 @@ public interface LabelPickListener {
 
   /**
    * Receives information about labels found in a call to {@link
-   * com.mapzen.tangram.MapController#pickLabel(float, float)}.
+   * com.mapzen.tangram.MapController#pickLabel(float, float)}. Note that a label refers
+   * to POI labels, search pins, route pins or more generally, any
+   * {@link com.mapzen.tangram.MapData} drawn using point style. It does not include
+   * {@link com.mapzen.android.graphics.model.Marker}s,
+   * {@link com.mapzen.android.graphics.model.Polygon}, or
+   * {@link com.mapzen.android.graphics.model.Polyline}.
+   * To receive pick information for {@link com.mapzen.android.graphics.model.Marker}s, use the
+   * {@link MarkerPickListener} interface and to receive pick information for
+   * {@link com.mapzen.android.graphics.model.Polygon} or
+   * {@link com.mapzen.android.graphics.model.Polyline}, use the {@link FeaturePickListener}
+   * interface.
    *
    * @param result Object containing information about the selected label. Can be null.
    * @param positionX The horizontal screen coordinate of the center of the feature. Will be 0 if

diff --git a/core/src/main/java/com/mapzen/android/graphics/MarkerPickListener.java b/core/src/main/java/com/mapzen/android/graphics/MarkerPickListener.java
@@ -3,7 +3,11 @@
 import com.mapzen.android.graphics.model.BitmapMarker;
 
 /**
- * Listener invoked when a marker on the map is selected.
+ * Listener invoked when a marker on the map is selected. Note that all
+ * {@link com.mapzen.android.graphics.model.Polygon}s,
+ * {@link com.mapzen.android.graphics.model.Polyline}s, and
+ * search/routing pins are not markers and will receive pick events via either the
+ * {@link LabelPickListener} or {@link FeaturePickListener} interfaces.
  */
 public interface MarkerPickListener {
   /**