revise docs for new sensor types. fix markup error causing tons of code font

Change-Id: I7635bbc44e03b50faeddf5c5fe50f7f47e2cde35

2 files changed, 62 insertions, 48 deletions

diff --git a/core/java/android/hardware/Sensor.java b/core/java/android/hardware/Sensor.java
index 71a5382..5cc1150 100644
--- a/core/java/android/hardware/Sensor.java
+++ b/core/java/android/hardware/Sensor.java
@@ -31,23 +31,23 @@ import android.os.Build;
 public final class Sensor {
 
     /**
-     * A constant describing an accelerometer sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing an accelerometer sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details.
      */
     public static final int TYPE_ACCELEROMETER = 1;
 
     /**
-     * A constant describing a magnetic field sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing a magnetic field sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details.
      */
     public static final int TYPE_MAGNETIC_FIELD = 2;
 
     /**
-     * A constant describing an orientation sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing an orientation sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details.
      *
      * @deprecated use {@link android.hardware.SensorManager#getOrientation
      *             SensorManager.getOrientation()} instead.
@@ -55,17 +55,21 @@ public final class Sensor {
     @Deprecated
     public static final int TYPE_ORIENTATION = 3;
 
-    /** A constant describing a gyroscope sensor type */
+    /** A constant describing a gyroscope sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details. */
     public static final int TYPE_GYROSCOPE = 4;
 
     /**
-     * A constant describing a light sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing a light sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details.
      */
     public static final int TYPE_LIGHT = 5;
 
-    /** A constant describing a pressure sensor type */
+    /** A constant describing a pressure sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details. */
     public static final int TYPE_PRESSURE = 6;
 
     /**
@@ -79,60 +83,66 @@ public final class Sensor {
     public static final int TYPE_TEMPERATURE = 7;
 
     /**
-     * A constant describing a proximity sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing a proximity sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details.
      */
     public static final int TYPE_PROXIMITY = 8;
 
     /**
      * A constant describing a gravity sensor type.
-     * See {@link android.hardware.SensorEvent SensorEvent}
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
      * for more details.
      */
     public static final int TYPE_GRAVITY = 9;
 
     /**
      * A constant describing a linear acceleration sensor type.
-     * See {@link android.hardware.SensorEvent SensorEvent}
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
      * for more details.
      */
     public static final int TYPE_LINEAR_ACCELERATION = 10;
 
     /**
      * A constant describing a rotation vector sensor type.
-     * See {@link android.hardware.SensorEvent SensorEvent}
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
      * for more details.
      */
     public static final int TYPE_ROTATION_VECTOR = 11;
 
     /**
      * A constant describing a relative humidity sensor type.
-     * See {@link android.hardware.SensorEvent SensorEvent}
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
      * for more details.
      */
     public static final int TYPE_RELATIVE_HUMIDITY = 12;
 
-    /** A constant describing an ambient temperature sensor type */
+    /** A constant describing an ambient temperature sensor type.
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values}
+     * for more details. */
     public static final int TYPE_AMBIENT_TEMPERATURE = 13;
 
     /**
-     * A constant describing a magnetic field uncalibrated sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
+     * A constant describing an uncalibrated magnetic field sensor type.
      * <p>
-     * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (calibration
-     * due to distortions that arise from magnetized iron, steel or permanenet magnets
-     * on the device) is reported separately. No periodic calibration is performed
-     * (i.e. there are no discontinuities in the data stream while using this sensor).
-     * Assumptions that the magnetic field is due to the Earth's poles is avoided.
-     * Factory calibration and temperature compensation are still performed.
+     * Similar to {@link #TYPE_MAGNETIC_FIELD} but the hard iron calibration (device calibration
+     * due to distortions that arise from magnetized iron, steel or permanent magnets on the
+     * device) is not considered in the given sensor values. However, such hard iron bias values
+     * are returned to you separately in the result {@link android.hardware.SensorEvent#values}
+     * so you may use them for custom calibrations. 
+     * <p>Also, no periodic calibration is performed
+     * (i.e. there are no discontinuities in the data stream while using this sensor) and
+     * assumptions that the magnetic field is due to the Earth's poles is avoided, but
+     * factory calibration and temperature compensation have been performed.
      * </p>
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more
+     * details.
      */
     public static final int TYPE_MAGNETIC_FIELD_UNCALIBRATED = 14;
 
     /**
-     * Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't
+     * A constant describing an uncalibrated rotation vector sensor type.
+     * <p>Identical to {@link #TYPE_ROTATION_VECTOR} except that it doesn't
      * use the geomagnetic field. Therefore the Y axis doesn't
      * point north, but instead to some other reference, that reference is
      * allowed to drift by the same order of magnitude as the gyroscope
@@ -143,32 +153,35 @@ public final class Sensor {
      * (without using the earth's geomagnetic field). However, the orientation
      * may drift somewhat over time.
      * </p>
+     * <p>See {@link android.hardware.SensorEvent#values SensorEvent.values} for more
+     * details.
      */
 
     public static final int TYPE_GAME_ROTATION_VECTOR = 15;
 
     /**
-     * A constant describing a gyroscope uncalibrated sensor type. See
-     * {@link android.hardware.SensorEvent#values SensorEvent.values} for more
-     * details.
-     * <p>
-     * No gyro-drift compensation is performed.
-     * Factory calibration and temperature compensation is still applied
+     * A constant describing an uncalibrated gyroscope sensor type.
+     * <p>Similar to {@link #TYPE_GYROSCOPE} but no gyro-drift compensation has been performed
+     * to adjust the given sensor values. However, such gyro-drift bias values
+     * are returned to you separately in the result {@link android.hardware.SensorEvent#values}
+     * so you may use them for custom calibrations.
+     * <p>Factory calibration and temperature compensation is still applied
      * to the rate of rotation (angular speeds).
      * </p>
+     * <p> See {@link android.hardware.SensorEvent#values SensorEvent.values} for more
+     * details.
      */
     public static final int TYPE_GYROSCOPE_UNCALIBRATED = 16;
 
     /**
      * A constant describing the significant motion trigger sensor.
-     * See {@link android.hardware.SensorEvent#values} for more details.
      * <p>
      * It triggers when an event occurs and then automatically disables
      * itself. The sensor continues to operate while the device is asleep
      * and will automatically wake the device to notify when significant
      * motion is detected. The application does not need to hold any wake
      * locks for this sensor to trigger.
-     * </p>
+     * <p>See {@link TriggerEvent} for more details.
      */
     public static final int TYPE_SIGNIFICANT_MOTION = 17;
 
diff --git a/core/java/android/hardware/SensorEvent.java b/core/java/android/hardware/SensorEvent.java
index 97b0cef..2bc0f9b 100644
--- a/core/java/android/hardware/SensorEvent.java
+++ b/core/java/android/hardware/SensorEvent.java
@@ -402,10 +402,9 @@ public class SensorEvent {
      * <li> values[0]: ambient (room) temperature in degree Celsius.</li>
      * </ul>
      *
-     * @see SensorEvent
-     * @see GeomagneticField
      *
-     * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD_UNCALIBRATED} </h4>
+     * <h4>{@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD_UNCALIBRATED
+     * Sensor.TYPE_MAGNETIC_FIELD_UNCALIBRATED}:</h4>
      * Similar to {@link android.hardware.Sensor#TYPE_MAGNETIC_FIELD},
      * but the hard iron calibration is reported separately instead of being included
      * in the measurement. Factory calibration and temperature compensation will still
@@ -437,7 +436,7 @@ public class SensorEvent {
      * Soft iron - These distortions arise due to the interaction with the earth's magentic
      * field.
      * </p>
-     * <h4> {@link android.hardware.Sensor#TYPE_GAME_ROTATION_VECTOR} </h4>
+     * <h4> {@link android.hardware.Sensor#TYPE_GAME_ROTATION_VECTOR}:</h4>
      * Identical to {@link android.hardware.Sensor#TYPE_ROTATION_VECTOR} except that it
      * doesn't use the geomagnetic field. Therefore the Y axis doesn't
      * point north, but instead to some other reference, that reference is
@@ -452,7 +451,8 @@ public class SensorEvent {
      * the estimated heading accuracy value.
      * </p>
      *
-     * <h4> {@link android.hardware.Sensor#TYPE_GYROSCOPE_UNCALIBRATED} </h4>
+     * <h4> {@link android.hardware.Sensor#TYPE_GYROSCOPE_UNCALIBRATED
+     * Sensor.TYPE_GYROSCOPE_UNCALIBRATED}:</h4>
      * All values are in radians/second and measure the rate of rotation
      * around the X, Y and Z axis. An estimation of the drift on each axis is
      * reported as well.
@@ -477,9 +477,10 @@ public class SensorEvent {
      * <li> values[5] : estimated drift around Z axis in rad/s </li>
      * </ul>
      * </p>
-     * <h4></h4>
-     * <h4> Pro Tip: Always use the length of the values array while performing operations
-     * on it. In earlier versions, this used to be always 3 which has changed now. </h4>
+     * <p><b>Pro Tip:</b> Always use the length of the values array while performing operations
+     * on it. In earlier versions, this used to be always 3 which has changed now. </p>
+     *
+     * @see GeomagneticField
      */
     public final float[] values;