am 0ac703fc: am 1108b845: Merge "Sensor documentation fixes." into lmp-docs

* commit '0ac703fc8f4569338acc823221089c62480f0d7c':
  Sensor documentation fixes.

core/java/android/hardware/Sensor.java

@@ -329,7 +329,11 @@ public final class Sensor {
      * A sensor of this type triggers an event each time a step is taken by the user. The only
      * allowed value to return is 1.0 and an event is generated for each step. Like with any other
      * event, the timestamp indicates when the event (here the step) occurred, this corresponds to
-     * when the foot hit the ground, generating a high variation in acceleration.
+     * when the foot hit the ground, generating a high variation in acceleration. This sensor is
+     * only for detecting every individual step as soon as it is taken, for example to perform dead
+     * reckoning. If you only need aggregate number of steps taken over a period of time, register
+     * for {@link #TYPE_STEP_COUNTER} instead. It is defined as a
+     * {@link Sensor#REPORTING_MODE_SPECIAL_TRIGGER} sensor.
      * <p>
      * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.
      */
@@ -349,7 +353,12 @@ public final class Sensor {
      * while activated. The value is returned as a float (with the fractional part set to zero) and
      * is reset to zero only on a system reboot. The timestamp of the event is set to the time when
      * the last step for that event was taken. This sensor is implemented in hardware and is
-     * expected to be low power.
+     * expected to be low power. If you want to continuously track the number of steps over a long
+     * period of time, do NOT unregister for this sensor, so that it keeps counting steps in the
+     * background even when the AP is in suspend mode and report the aggregate count when the AP
+     * is awake. Application needs to stay registered for this sensor because step counter does not
+     * count steps if it is not activated. This sensor is ideal for fitness tracking applications.
+     * It is defined as an {@link Sensor#REPORTING_MODE_ON_CHANGE} sensor.
      * <p>
      * See {@link android.hardware.SensorEvent#values SensorEvent.values} for more details.
      */
@@ -750,31 +759,41 @@ public final class Sensor {
     }
 
     /**
-     * Returns whether this sensor is a wake-up sensor.
+     * Returns true if the sensor is a wake-up sensor.
      * <p>
-     * Wake up sensors wake the application processor up when they have events to deliver. When a
+     * <b>Application Processor Power modes</b> <p>
-     * wake up sensor is registered to without batching enabled, each event will wake the
+     * Application Processor(AP), is the processor on which applications run.  When no wake lock is held
-     * application processor up.
+     * and the user is not interacting with the device, this processor can enter a “Suspend” mode,
+     * reducing the power consumption by 10 times or more.
+     * </p>
      * <p>
-     * When a wake up sensor is registered to with batching enabled, it
+     * <b>Non-wake-up sensors</b> <p>
-     * wakes the application processor up when maxReportingLatency has elapsed or when the hardware
+     * Non-wake-up sensors are sensors that do not wake the AP out of suspend to report data. While
-     * FIFO storing the events from wake up sensors is getting full.
+     * the AP is in suspend mode, the sensors continue to function and generate events, which are
+     * put in a hardware FIFO. The events in the FIFO are delivered to the application when the AP
+     * wakes up. If the FIFO was too small to store all events generated while the AP was in
+     * suspend mode, the older events are lost: the oldest data is dropped to accommodate the newer
+     * data. In the extreme case where the FIFO is non-existent {@code maxFifoEventCount() == 0},
+     * all events generated while the AP was in suspend mode are lost. Applications using
+     * non-wake-up sensors should usually:
+     * <ul>
+     * <li>Either unregister from the sensors when they do not need them, usually in the activity’s
+     * {@code onPause} method. This is the most common case.
+     * <li>Or realize that the sensors are consuming some power while the AP is in suspend mode and
+     * that even then, some events might be lost.
+     * </ul>
+     * </p>
      * <p>
-     * Non-wake up sensors never wake the application processor up. Their events are only reported
+     * <b>Wake-up sensors</b> <p>
-     * when the application processor is awake, for example because the application holds a wake
+     * In opposition to non-wake-up sensors, wake-up sensors ensure that their data is delivered
-     * lock, or another source woke the application processor up.
+     * independently of the state of the AP. While the AP is awake, the wake-up sensors behave
-     * <p>
+     * like non-wake-up-sensors. When the AP is asleep, wake-up sensors wake up the AP to deliver
-     * When a non-wake up sensor is registered to without batching enabled, the measurements made
+     * events. That is, the AP will wake up and the sensor will deliver the events before the
-     * while the application processor is asleep might be lost and never returned.
+     * maximum reporting latency is elapsed or the hardware FIFO gets full. See {@link
-     * <p>
+     * SensorManager#registerListener(SensorEventListener, Sensor, int, int)} for more details.
-     * When a non-wake up sensor is registered to with batching enabled, the measurements made while
+     * </p>
-     * the application processor is asleep are stored in the hardware FIFO for non-wake up sensors.
+     *
-     * When this FIFO gets full, new events start overwriting older events. When the application
+     * @return <code>true</code> if this is a wake-up sensor, <code>false</code> otherwise.
-     * then wakes up, the latest events are returned, and some old events might be lost. The number
-     * of events actually returned depends on the hardware FIFO size, as well as on what other
-     * sensors are activated. If losing sensor events is not acceptable during batching, you must
-     * use the wake-up version of the sensor.
-     * @return true if this is a wake up sensor, false otherwise.
      */
     public boolean isWakeUpSensor() {
         return (mFlags & SENSOR_FLAG_WAKE_UP_SENSOR) != 0;

core/java/android/hardware/SensorEventListener2.java

@@ -21,15 +21,16 @@ package android.hardware;
  */
 public interface SensorEventListener2 extends SensorEventListener {
     /**
-     * Called after flush() is completed. All the events in the batch at the point when
+     * Called after flush() is completed. All the events in the batch at the point when the flush
-     * the flush was called have been delivered to the applications registered for those
+     * was called have been delivered to the applications registered for those sensor events. In
-     * sensor events. Flush Complete Events are sent ONLY to the application that has
+     * {@link android.os.Build.VERSION_CODES#KITKAT}, applications may receive flush complete events
-     * explicitly called flush(). If the hardware FIFO is flushed due to some other
+     * even if some other application has called flush() on the same sensor. Starting with
-     * application calling flush(), flush complete event is not delivered to this application.
+     * {@link android.os.Build.VERSION_CODES#LOLLIPOP}, flush Complete events are sent ONLY to the
+     * application that has explicitly called flush(). If the hardware FIFO is flushed due to some
+     * other application calling flush(), flush complete event is not delivered to this application.
      * <p>
      *
      * @param sensor The {@link android.hardware.Sensor Sensor} on which flush was called.
-     *
      * @see android.hardware.SensorManager#flush(SensorEventListener)
      */
     public void onFlushCompleted(Sensor sensor);

core/java/android/hardware/SensorManager.java

@@ -626,73 +626,90 @@ public abstract class SensorManager {
     protected abstract void unregisterListenerImpl(SensorEventListener listener, Sensor sensor);
 
     /**
-     * Registers a {@link android.hardware.SensorEventListener
+     * Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
-     * SensorEventListener} for the given sensor.
+     * sensor at the given sampling frequency.
-     *
+     * <p>
-     * <p class="note"></p>
+     * The events will be delivered to the provided {@code SensorEventListener} as soon as they are
-     * Note: Don't use this method with a one shot trigger sensor such as
+     * available. To reduce the power consumption, applications can use
-     * {@link Sensor#TYPE_SIGNIFICANT_MOTION}.
+     * {@link #registerListener(SensorEventListener, Sensor, int, int)} instead and specify a
-     * Use {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead.
+     * positive non-zero maximum reporting latency.
+     * </p>
+     * <p>
+     * In the case of non-wake-up sensors, the events are only delivered while the Application
+     * Processor (AP) is not in suspend mode. See {@link Sensor#isWakeUpSensor()} for more details.
+     * To ensure delivery of events from non-wake-up sensors even when the screen is OFF, the
+     * application registering to the sensor must hold a partial wake-lock to keep the AP awake,
+     * otherwise some events might be lost while the AP is asleep. Note that although events might
+     * be lost while the AP is asleep, the sensor will still consume power if it is not explicitly
+     * deactivated by the application. Applications must unregister their {@code
+     * SensorEventListener}s in their activity's {@code onPause()} method to avoid consuming power
+     * while the device is inactive.  See {@link #registerListener(SensorEventListener, Sensor, int,
+     * int)} for more details on hardware FIFO (queueing) capabilities and when some sensor events
+     * might be lost.
+     * </p>
+     * <p>
+     * In the case of wake-up sensors, each event generated by the sensor will cause the AP to
+     * wake-up, ensuring that each event can be delivered. Because of this, registering to a wake-up
+     * sensor has very significant power implications. Call {@link Sensor#isWakeUpSensor()} to check
+     * whether a sensor is a wake-up sensor. See
+     * {@link #registerListener(SensorEventListener, Sensor, int, int)} for information on how to
+     * reduce the power impact of registering to wake-up sensors.
+     * </p>
+     * <p class="note">
+     * Note: Don't use this method with one-shot trigger sensors such as
+     * {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
+     * {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. Use
+     * {@link Sensor#getReportingMode()} to obtain the reporting mode of a given sensor.
      * </p>
      *
-     * @param listener
+     * @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object.
-     *        A {@link android.hardware.SensorEventListener SensorEventListener}
+     * @param sensor The {@link android.hardware.Sensor Sensor} to register to.
-     *        object.
+     * @param samplingPeriodUs The rate {@link android.hardware.SensorEvent sensor events} are
-     *
+     *            delivered at. This is only a hint to the system. Events may be received faster or
-     * @param sensor
+     *            slower than the specified rate. Usually events are received faster. The value must
-     *        The {@link android.hardware.Sensor Sensor} to register to.
+     *            be one of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
-     *
+     *            {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST} or, the desired delay
-     * @param rateUs
+     *            between events in microseconds. Specifying the delay in microseconds only works
-     *        The rate {@link android.hardware.SensorEvent sensor events} are
+     *            from Android 2.3 (API level 9) onwards. For earlier releases, you must use one of
-     *        delivered at. This is only a hint to the system. Events may be
+     *            the {@code SENSOR_DELAY_*} constants.
-     *        received faster or slower than the specified rate. Usually events
+     * @return <code>true</code> if the sensor is supported and successfully enabled.
-     *        are received faster. The value must be one of
-     *        {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
-     *        {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}
-     *        or, the desired delay between events in microseconds.
-     *        Specifying the delay in microseconds only works from Android
-     *        2.3 (API level 9) onwards. For earlier releases, you must use
-     *        one of the {@code SENSOR_DELAY_*} constants.
-     *
-     * @return <code>true</code> if the sensor is supported and successfully
-     *         enabled.
-     *
      * @see #registerListener(SensorEventListener, Sensor, int, Handler)
      * @see #unregisterListener(SensorEventListener)
      * @see #unregisterListener(SensorEventListener, Sensor)
-     *
      */
-    public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs) {
+    public boolean registerListener(SensorEventListener listener, Sensor sensor,
-        return registerListener(listener, sensor, rateUs, null);
+            int samplingPeriodUs) {
+        return registerListener(listener, sensor, samplingPeriodUs, null);
     }
 
     /**
-     * Enables batch mode for a sensor with the given rate and maxBatchReportLatency. If the
+     * Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
-     * underlying hardware does not support batch mode, this defaults to
+     * sensor at the given sampling frequency and the given maximum reporting latency.
-     * {@link #registerListener(SensorEventListener, Sensor, int)} and other parameters are
-     * ignored. In non-batch mode, all sensor events must be reported as soon as they are detected.
-     * While in batch mode, sensor events do not need to be reported as soon as they are detected.
-     * They can be temporarily stored in batches and reported in batches, as long as no event is
-     * delayed by more than "maxBatchReportLatency" microseconds. That is, all events since the
-     * previous batch are recorded and returned all at once. This allows to reduce the amount of
-     * interrupts sent to the SoC, and allows the SoC to switch to a lower power state (Idle) while
-     * the sensor is capturing and batching data.
      * <p>
-     * Registering to a sensor in batch mode will not prevent the SoC from going to suspend mode. In
+     * This function is similar to {@link #registerListener(SensorEventListener, Sensor, int)} but
-     * this case, the sensor will continue to gather events and store it in a hardware FIFO. If the
+     * it allows events to stay temporarily in the hardware FIFO (queue) before being delivered. The
-     * FIFO gets full before the AP wakes up again, some events will be lost, as the older events
+     * events can be stored in the hardware FIFO up to {@code maxReportLatencyUs} microseconds. Once
-     * get overwritten by new events in the hardware FIFO. This can be avoided by holding a wake
+     * one of the events in the FIFO needs to be reported, all of the events in the FIFO are
-     * lock. If the application holds a wake lock, the SoC will not go to suspend mode, so no events
+     * reported sequentially. This means that some events will be reported before the maximum
-     * will be lost, as the events will be reported before the FIFO gets full.
+     * reporting latency has elapsed.
-     * </p>
+     * </p><p>
-     * <p>
+     * When {@code maxReportLatencyUs} is 0, the call is equivalent to a call to
-     * Batching is always best effort. If a different application requests updates in continuous
+     * {@link #registerListener(SensorEventListener, Sensor, int)}, as it requires the events to be
-     * mode, this application will also get events in continuous mode. Batch mode updates can be
+     * delivered as soon as possible.
-     * unregistered by calling {@link #unregisterListener(SensorEventListener)}.
+     * </p><p>
+     * When {@code sensor.maxFifoEventCount()} is 0, the sensor does not use a FIFO, so the call
+     * will also be equivalent to {@link #registerListener(SensorEventListener, Sensor, int)}.
+     * </p><p>
+     * Setting {@code maxReportLatencyUs} to a positive value allows to reduce the number of
+     * interrupts the AP (Application Processor) receives, hence reducing power consumption, as the
+     * AP can switch to a lower power state while the sensor is capturing the data. This is
+     * especially important when registering to wake-up sensors, for which each interrupt causes the
+     * AP to wake up if it was in suspend mode. See {@link Sensor#isWakeUpSensor()} for more
+     * information on wake-up sensors.
      * </p>
      * <p class="note">
      * </p>
-     * Note: Don't use this method with a one shot trigger sensor such as
+     * Note: Don't use this method with one-shot trigger sensors such as
      * {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
      * {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. </p>
      *
@@ -701,118 +718,104 @@ public abstract class SensorManager {
      *            flush complete notifications, it should register with
      *            {@link android.hardware.SensorEventListener SensorEventListener2} instead.
      * @param sensor The {@link android.hardware.Sensor Sensor} to register to.
-     * @param rateUs The desired delay between two consecutive events in microseconds. This is only
+     * @param samplingPeriodUs The desired delay between two consecutive events in microseconds.
-     *            a hint to the system. Events may be received faster or slower than the specified
+     *            This is only a hint to the system. Events may be received faster or slower than
-     *            rate. Usually events are received faster. Can be one of
+     *            the specified rate. Usually events are received faster. Can be one of
      *            {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
      *            {@link #SENSOR_DELAY_GAME}, {@link #SENSOR_DELAY_FASTEST} or the delay in
      *            microseconds.
-     * @param maxBatchReportLatencyUs An event in the batch can be delayed by at most
+     * @param maxReportLatencyUs Maximum time in microseconds that events can be delayed before
-     *            maxBatchReportLatency microseconds. More events can be batched if this value is
+     *            being reported to the application. A large value allows reducing the power
-     *            large. If this is set to zero, batch mode is disabled and events are delivered in
+     *            consumption associated with the sensor. If maxReportLatencyUs is set to zero,
-     *            continuous mode as soon as they are available which is equivalent to calling
+     *            events are delivered as soon as they are available, which is equivalent to calling
      *            {@link #registerListener(SensorEventListener, Sensor, int)}.
-     * @return <code>true</code> if batch mode is successfully enabled for this sensor,
+     * @return <code>true</code> if the sensor is supported and successfully enabled.
-     *         <code>false</code> otherwise.
      * @see #registerListener(SensorEventListener, Sensor, int)
      * @see #unregisterListener(SensorEventListener)
      * @see #flush(SensorEventListener)
      */
-    public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
+    public boolean registerListener(SensorEventListener listener, Sensor sensor,
-            int maxBatchReportLatencyUs) {
+            int samplingPeriodUs, int maxReportLatencyUs) {
-        int delay = getDelay(rateUs);
+        int delay = getDelay(samplingPeriodUs);
-        return registerListenerImpl(listener, sensor, delay, null, maxBatchReportLatencyUs, 0);
+        return registerListenerImpl(listener, sensor, delay, null, maxReportLatencyUs, 0);
     }
 
     /**
      * Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
      * sensor. Events are delivered in continuous mode as soon as they are available. To reduce the
-     * battery usage, use {@link #registerListener(SensorEventListener, Sensor, int, int)} which
+     * power consumption, applications can use
-     * enables batch mode for the sensor.
+     * {@link #registerListener(SensorEventListener, Sensor, int, int)} instead and specify a
-     *
+     * positive non-zero maximum reporting latency.
-     * <p class="note"></p>
+     * <p class="note">
-     * Note: Don't use this method with a one shot trigger sensor such as
-     * {@link Sensor#TYPE_SIGNIFICANT_MOTION}.
-     * Use {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead.
      * </p>
+     * Note: Don't use this method with a one shot trigger sensor such as
+     * {@link Sensor#TYPE_SIGNIFICANT_MOTION}. Use
+     * {@link #requestTriggerSensor(TriggerEventListener, Sensor)} instead. </p>
      *
-     * @param listener
+     * @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object.
-     *        A {@link android.hardware.SensorEventListener SensorEventListener}
+     * @param sensor The {@link android.hardware.Sensor Sensor} to register to.
-     *        object.
+     * @param samplingPeriodUs The rate {@link android.hardware.SensorEvent sensor events} are
-     *
+     *            delivered at. This is only a hint to the system. Events may be received faster or
-     * @param sensor
+     *            slower than the specified rate. Usually events are received faster. The value must
-     *        The {@link android.hardware.Sensor Sensor} to register to.
+     *            be one of {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
-     *
+     *            {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST} or, the desired
-     * @param rateUs
+     *            delay between events in microseconds. Specifying the delay in microseconds only
-     *        The rate {@link android.hardware.SensorEvent sensor events} are
+     *            works from Android 2.3 (API level 9) onwards. For earlier releases, you must use
-     *        delivered at. This is only a hint to the system. Events may be
+     *            one of the {@code SENSOR_DELAY_*} constants.
-     *        received faster or slower than the specified rate. Usually events
+     * @param handler The {@link android.os.Handler Handler} the {@link android.hardware.SensorEvent
-     *        are received faster. The value must be one of
+     *            sensor events} will be delivered to.
-     *        {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
-     *        {@link #SENSOR_DELAY_GAME}, or {@link #SENSOR_DELAY_FASTEST}.
-     *        or, the desired delay between events in microseconds.
-     *        Specifying the delay in microseconds only works from Android
-     *        2.3 (API level 9) onwards. For earlier releases, you must use
-     *        one of the {@code SENSOR_DELAY_*} constants.
-     *
-     * @param handler
-     *        The {@link android.os.Handler Handler} the
-     *        {@link android.hardware.SensorEvent sensor events} will be
-     *        delivered to.
-     *
      * @return <code>true</code> if the sensor is supported and successfully enabled.
-     *
      * @see #registerListener(SensorEventListener, Sensor, int)
      * @see #unregisterListener(SensorEventListener)
      * @see #unregisterListener(SensorEventListener, Sensor)
      */
-    public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
+    public boolean registerListener(SensorEventListener listener, Sensor sensor,
-            Handler handler) {
+            int samplingPeriodUs, Handler handler) {
-        int delay = getDelay(rateUs);
+        int delay = getDelay(samplingPeriodUs);
         return registerListenerImpl(listener, sensor, delay, handler, 0, 0);
     }
 
     /**
-     * Enables batch mode for a sensor with the given rate and maxBatchReportLatency.
+     * Registers a {@link android.hardware.SensorEventListener SensorEventListener} for the given
+     * sensor at the given sampling frequency and the given maximum reporting latency.
+     *
      * @param listener A {@link android.hardware.SensorEventListener SensorEventListener} object
      *            that will receive the sensor events. If the application is interested in receiving
      *            flush complete notifications, it should register with
      *            {@link android.hardware.SensorEventListener SensorEventListener2} instead.
      * @param sensor The {@link android.hardware.Sensor Sensor} to register to.
-     * @param rateUs The desired delay between two consecutive events in microseconds. This is only
+     * @param samplingPeriodUs The desired delay between two consecutive events in microseconds.
-     *            a hint to the system. Events may be received faster or slower than the specified
+     *            This is only a hint to the system. Events may be received faster or slower than
-     *            rate. Usually events are received faster. Can be one of
+     *            the specified rate. Usually events are received faster. Can be one of
      *            {@link #SENSOR_DELAY_NORMAL}, {@link #SENSOR_DELAY_UI},
      *            {@link #SENSOR_DELAY_GAME}, {@link #SENSOR_DELAY_FASTEST} or the delay in
      *            microseconds.
-     * @param maxBatchReportLatencyUs An event in the batch can be delayed by at most
+     * @param maxReportLatencyUs Maximum time in microseconds that events can be delayed before
-     *            maxBatchReportLatency microseconds. More events can be batched if this value is
+     *            being reported to the application. A large value allows reducing the power
-     *            large. If this is set to zero, batch mode is disabled and events are delivered in
+     *            consumption associated with the sensor. If maxReportLatencyUs is set to zero,
-     *            continuous mode as soon as they are available which is equivalent to calling
+     *            events are delivered as soon as they are available, which is equivalent to calling
      *            {@link #registerListener(SensorEventListener, Sensor, int)}.
-     * @param handler The {@link android.os.Handler Handler} the
+     * @param handler The {@link android.os.Handler Handler} the {@link android.hardware.SensorEvent
-     *        {@link android.hardware.SensorEvent sensor events} will be delivered to.
+     *            sensor events} will be delivered to.
-     *
+     * @return <code>true</code> if the sensor is supported and successfully enabled.
-     * @return <code>true</code> if batch mode is successfully enabled for this sensor,
-     *         <code>false</code> otherwise.
      * @see #registerListener(SensorEventListener, Sensor, int, int)
      */
-    public boolean registerListener(SensorEventListener listener, Sensor sensor, int rateUs,
+    public boolean registerListener(SensorEventListener listener, Sensor sensor, int samplingPeriodUs,
-            int maxBatchReportLatencyUs, Handler handler) {
+            int maxReportLatencyUs, Handler handler) {
-        int delayUs = getDelay(rateUs);
+        int delayUs = getDelay(samplingPeriodUs);
-        return registerListenerImpl(listener, sensor, delayUs, handler, maxBatchReportLatencyUs, 0);
+        return registerListenerImpl(listener, sensor, delayUs, handler, maxReportLatencyUs, 0);
     }
 
     /** @hide */
     protected abstract boolean registerListenerImpl(SensorEventListener listener, Sensor sensor,
-            int delayUs, Handler handler, int maxBatchReportLatencyUs, int reservedFlags);
+            int delayUs, Handler handler, int maxReportLatencyUs, int reservedFlags);
 
 
     /**
-     * Flushes the batch FIFO of all the sensors registered for this listener. If there are events
+     * Flushes the FIFO of all the sensors registered for this listener. If there are events
-     * in the FIFO of the sensor, they are returned as if the batch timeout in the FIFO of the
+     * in the FIFO of the sensor, they are returned as if the maxReportLantecy of the FIFO has
-     * sensors had expired. Events are returned in the usual way through the SensorEventListener.
+     * expired. Events are returned in the usual way through the SensorEventListener.
-     * This call doesn't affect the batch timeout for this sensor. This call is asynchronous and
+     * This call doesn't affect the maxReportLantecy for this sensor. This call is asynchronous and
      * returns immediately.
      * {@link android.hardware.SensorEventListener2#onFlushCompleted onFlushCompleted} is called
      * after all the events in the batch at the time of calling this method have been delivered