docs: Clarify the callback mechanisms for LocationRequest

and clarify horizontal geofencing

Change-Id: I8ff264d7a12c8ec3c79854e008aeeb5f922ad459

Author: scottamain

location/java/android/location/Geofence.java

@@ -22,7 +22,7 @@
 /**
  * Represents a geographical boundary, also known as a geofence.
  *
- * <p>Currently only circular geofences are supported.
+ * <p>Currently only circular geofences are supported and they do not support altitude changes.
  */
 public final class Geofence implements Parcelable {
     /** @hide */
@@ -34,7 +34,7 @@ public final class Geofence implements Parcelable {
     private final float mRadius;
 
     /**
-     * Create a horizontal, circular geofence.
+     * Create a circular geofence (on a flat, horizontal plane).
      *
      * @param latitude latitude in degrees
      * @param longitude longitude in degrees

location/java/android/location/LocationManager.java

@@ -811,6 +811,10 @@ public void requestSingleUpdate(Criteria criteria, PendingIntent intent) {
     /**
      * Register for fused location updates using a LocationRequest and callback.
      *
+     * <p>Upon a location update, the system delivers the new {@link Location} to the
+     * provided {@link LocationListener}, by calling its {@link
+     * LocationListener#onLocationChanged} method.</p>
+     *
      * <p>The system will automatically select and enable the best providers
      * to compute a location for your application. It may use only passive
      * locations, or just a single location source, or it may fuse together
@@ -869,6 +873,10 @@ public void requestLocationUpdates(LocationRequest request, LocationListener lis
     /**
      * Register for fused location updates using a LocationRequest and a pending intent.
      *
+     * <p>Upon a location update, the system delivers the new {@link Location} with your provided
+     * {@link PendingIntent}, as the value for {@link LocationManager#KEY_LOCATION_CHANGED}
+     * in the intent's extras.</p>
+     *
      * <p> To unregister for Location updates, use: {@link #removeUpdates(PendingIntent)}.
      *
      * <p> See {@link #requestLocationUpdates(LocationRequest, LocationListener, Looper)}