Merge "Doc update: manual merge of changes from jb-mr1.1" into jb-mr2-dev

core/java/android/hardware/SensorEvent.java

@@ -63,40 +63,40 @@ public class SensorEvent {
      *
      * <h4>{@link android.hardware.Sensor#TYPE_ACCELEROMETER
      * Sensor.TYPE_ACCELEROMETER}:</h4> All values are in SI units (m/s^2)
-     * 
+     *
      * <ul>
      * <li> values[0]: Acceleration minus Gx on the x-axis </li>
      * <li> values[1]: Acceleration minus Gy on the y-axis </li>
      * <li> values[2]: Acceleration minus Gz on the z-axis </li>
      * </ul>
-     * 
+     *
      * <p>
      * A sensor of this type measures the acceleration applied to the device
      * (<b>Ad</b>). Conceptually, it does so by measuring forces applied to the
      * sensor itself (<b>Fs</b>) using the relation:
      * </p>
-     * 
+     *
      * <b><center>Ad = - &#8721;Fs / mass</center></b>
-     * 
+     *
      * <p>
      * In particular, the force of gravity is always influencing the measured
      * acceleration:
      * </p>
-     * 
+     *
      * <b><center>Ad = -g - &#8721;F / mass</center></b>
-     * 
+     *
      * <p>
      * For this reason, when the device is sitting on a table (and obviously not
      * accelerating), the accelerometer reads a magnitude of <b>g</b> = 9.81
      * m/s^2
      * </p>
-     * 
+     *
      * <p>
      * Similarly, when the device is in free-fall and therefore dangerously
      * accelerating towards to ground at 9.81 m/s^2, its accelerometer reads a
      * magnitude of 0 m/s^2.
      * </p>
-     * 
+     *
      * <p>
      * It should be apparent that in order to measure the real acceleration of
      * the device, the contribution of the force of gravity must be eliminated.
@@ -129,23 +129,23 @@ public class SensorEvent {
      * <ul>
      * <li>When the device lies flat on a table and is pushed on its left side
      * toward the right, the x acceleration value is positive.</li>
-     * 
+     *
      * <li>When the device lies flat on a table, the acceleration value is
      * +9.81, which correspond to the acceleration of the device (0 m/s^2) minus
      * the force of gravity (-9.81 m/s^2).</li>
-     * 
+     *
      * <li>When the device lies flat on a table and is pushed toward the sky
      * with an acceleration of A m/s^2, the acceleration value is equal to
      * A+9.81 which correspond to the acceleration of the device (+A m/s^2)
      * minus the force of gravity (-9.81 m/s^2).</li>
      * </ul>
-     * 
-     * 
+     *
+     *
      * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD
      * Sensor.TYPE_MAGNETIC_FIELD}:</h4>
      * All values are in micro-Tesla (uT) and measure the ambient magnetic field
      * in the X, Y and Z axis.
-     * 
+     *
      * <h4>{@link android.hardware.Sensor#TYPE_GYROSCOPE Sensor.TYPE_GYROSCOPE}:
      * </h4> All values are in radians/second and measure the rate of rotation
      * around the device's local X, Y and Z axis. The coordinate system is the
@@ -221,7 +221,7 @@ public class SensorEvent {
      * <ul>
      * <li>values[0]: Ambient light level in SI lux units </li>
      * </ul>
-     * 
+     *
      * <h4>{@link android.hardware.Sensor#TYPE_PRESSURE Sensor.TYPE_PRESSURE}:</h4>
      * <ul>
      * <li>values[0]: Atmospheric pressure in hPa (millibar) </li>
@@ -229,18 +229,18 @@ public class SensorEvent {
      *
      * <h4>{@link android.hardware.Sensor#TYPE_PROXIMITY Sensor.TYPE_PROXIMITY}:
      * </h4>
-     * 
+     *
      * <ul>
      * <li>values[0]: Proximity sensor distance measured in centimeters </li>
      * </ul>
-     * 
+     *
      * <p>
      * <b>Note:</b> Some proximity sensors only support a binary <i>near</i> or
      * <i>far</i> measurement. In this case, the sensor should report its
      * {@link android.hardware.Sensor#getMaximumRange() maximum range} value in
      * the <i>far</i> state and a lesser value in the <i>near</i> state.
      * </p>
-     * 
+     *
      *  <h4>{@link android.hardware.Sensor#TYPE_GRAVITY Sensor.TYPE_GRAVITY}:</h4>
      *  <p>A three dimensional vector indicating the direction and magnitude of gravity.  Units
      *  are m/s^2. The coordinate system is the same as is used by the acceleration sensor.</p>
@@ -299,23 +299,30 @@ public class SensorEvent {
      *
      * <h4>{@link android.hardware.Sensor#TYPE_ORIENTATION
      * Sensor.TYPE_ORIENTATION}:</h4> All values are angles in degrees.
-     * 
+     *
      * <ul>
      * <li> values[0]: Azimuth, angle between the magnetic north direction and the
      * y-axis, around the z-axis (0 to 359). 0=North, 90=East, 180=South,
-     * 270=West </li>
-     * <li> values[1]: Pitch, rotation around x-axis (-180 to 180), with positive
-     * values when the z-axis moves <b>toward</b> the y-axis. </li>
-     * <li> values[2]: Roll, rotation around y-axis (-90 to 90), with positive values
-     * when the x-axis moves <b>toward</b> the z-axis. </li>
+     * 270=West
+     * </p>
+     *
+     * <p>
+     * values[1]: Pitch, rotation around x-axis (-180 to 180), with positive
+     * values when the z-axis moves <b>toward</b> the y-axis.
+     * </p>
+     *
+     * <p>
+     * values[2]: Roll, rotation around the x-axis (-90 to 90)
+     * increasing as the device moves clockwise.
+     * </p>
      * </ul>
-     * 
+     *
      * <p>
      * <b>Note:</b> This definition is different from <b>yaw, pitch and roll</b>
      * used in aviation where the X axis is along the long side of the plane
      * (tail to nose).
      * </p>
-     * 
+     *
      * <p>
      * <b>Note:</b> This sensor type exists for legacy reasons, please use
      * {@link android.hardware.SensorManager#getRotationMatrix
@@ -325,7 +332,7 @@ public class SensorEvent {
      * {@link android.hardware.SensorManager#getOrientation getOrientation()} to
      * compute these values instead.
      * </p>
-     * 
+     *
      * <p>
      * <b>Important note:</b> For historical reasons the roll angle is positive
      * in the clockwise direction (mathematically speaking, it should be