frameworks/native: document native types and enums

Change-Id: Id94b610f27b87426abb30e13484cbd16990aa995
diff --git a/include/android/sensor.h b/include/android/sensor.h
index d58c460..4600dad 100644
--- a/include/android/sensor.h
+++ b/include/android/sensor.h
@@ -14,6 +14,14 @@
  * limitations under the License.
  */
 
+/**
+ * @addtogroup Sensor
+ * @{
+ */
+
+/**
+ * @file sensor.h
+ */
 
 #ifndef ANDROID_SENSOR_H
 #define ANDROID_SENSOR_H
@@ -34,7 +42,7 @@
  *   - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
  */
 
-/*
+/**
  * Structures and functions to receive and process sensor events in
  * native code.
  *
@@ -49,37 +57,82 @@
 #endif
 
 
-/*
- * Sensor types
+/**
+ * Sensor types.
  * (keep in sync with hardware/sensor.h)
  */
-
 enum {
+    /**
+     * {@link ASENSOR_TYPE_ACCELEROMETER}
+     * reporting-mode: continuous
+     *
+     *  All values are in SI units (m/s^2) and measure the acceleration of the
+     *  device minus the force of gravity.
+     */
     ASENSOR_TYPE_ACCELEROMETER      = 1,
+    /**
+     * {@link ASENSOR_TYPE_MAGNETIC_FIELD}
+     * reporting-mode: continuous
+     *
+     *  All values are in micro-Tesla (uT) and measure the geomagnetic
+     *  field in the X, Y and Z axis.
+     */
     ASENSOR_TYPE_MAGNETIC_FIELD     = 2,
+    /**
+     * {@link ASENSOR_TYPE_GYROSCOPE}
+     * reporting-mode: continuous
+     *
+     *  All values are in radians/second and measure the rate of rotation
+     *  around the X, Y and Z axis.
+     */
     ASENSOR_TYPE_GYROSCOPE          = 4,
+    /**
+     * {@link ASENSOR_TYPE_LIGHT}
+     * reporting-mode: on-change
+     *
+     * The light sensor value is returned in SI lux units.
+     */
     ASENSOR_TYPE_LIGHT              = 5,
+    /**
+     * {@link ASENSOR_TYPE_PROXIMITY}
+     * reporting-mode: on-change
+     *
+     * The proximity sensor which turns the screen off and back on during calls is the
+     * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
+     * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
+     * SENSOR_FLAG_WAKE_UP.
+     * The value corresponds to the distance to the nearest object in centimeters.
+     */
     ASENSOR_TYPE_PROXIMITY          = 8
 };
 
-/*
- * Sensor accuracy measure
+/**
+ * Sensor accuracy measure.
  */
 enum {
+    /** no contact */
     ASENSOR_STATUS_NO_CONTACT       = -1,
+    /** unreliable */
     ASENSOR_STATUS_UNRELIABLE       = 0,
+    /** low accuracy */
     ASENSOR_STATUS_ACCURACY_LOW     = 1,
+    /** medium accuracy */
     ASENSOR_STATUS_ACCURACY_MEDIUM  = 2,
+    /** high accuracy */
     ASENSOR_STATUS_ACCURACY_HIGH    = 3
 };
 
-/*
+/**
  * Sensor Reporting Modes.
  */
 enum {
+    /** continuous reporting */
     AREPORTING_MODE_CONTINUOUS = 0,
+    /** reporting on change */
     AREPORTING_MODE_ON_CHANGE = 1,
+    /** on shot reporting */
     AREPORTING_MODE_ONE_SHOT = 2,
+    /** special trigger reporting */
     AREPORTING_MODE_SPECIAL_TRIGGER = 3
 };
 
@@ -87,14 +140,14 @@
  * A few useful constants
  */
 
-/* Earth's gravity in m/s^2 */
+/** Earth's gravity in m/s^2 */
 #define ASENSOR_STANDARD_GRAVITY            (9.80665f)
-/* Maximum magnetic field on Earth's surface in uT */
+/** Maximum magnetic field on Earth's surface in uT */
 #define ASENSOR_MAGNETIC_FIELD_EARTH_MAX    (60.0f)
-/* Minimum magnetic field on Earth's surface in uT*/
+/** Minimum magnetic field on Earth's surface in uT*/
 #define ASENSOR_MAGNETIC_FIELD_EARTH_MIN    (30.0f)
 
-/*
+/**
  * A sensor event.
  */
 
@@ -180,19 +233,82 @@
 } ASensorEvent;
 
 struct ASensorManager;
+/**
+ * {@link ASensorManager} is an opaque type to manage sensors and
+ * events queues.
+ *
+ * {@link ASensorManager} is a singleton that can be obtained using
+ * ASensorManager_getInstance().
+ *
+ * This file provides a set of functions that uses {@link
+ * ASensorManager} to access and list hardware sensors, and
+ * create and destroy event queues:
+ * - ASensorManager_getSensorList()
+ * - ASensorManager_getDefaultSensor()
+ * - ASensorManager_getDefaultSensorEx()
+ * - ASensorManager_createEventQueue()
+ * - ASensorManager_destroyEventQueue()
+ */
 typedef struct ASensorManager ASensorManager;
 
+
 struct ASensorEventQueue;
+/**
+ * {@link ASensorEventQueue} is an opaque type that provides access to
+ * {@link ASensorEvent} from hardware sensors.
+ *
+ * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
+ *
+ * This file provides a set of functions to enable and disable
+ * sensors, check and get events, and set event rates on a {@link
+ * ASensorEventQueue}.
+ * - ASensorEventQueue_enableSensor()
+ * - ASensorEventQueue_disableSensor()
+ * - ASensorEventQueue_hasEvents()
+ * - ASensorEventQueue_getEvents()
+ * - ASensorEventQueue_setEventRate()
+ */
 typedef struct ASensorEventQueue ASensorEventQueue;
 
 struct ASensor;
+/**
+ * {@link ASensor} is an opaque type that provides information about
+ * an hardware sensors.
+ *
+ * A {@link ASensor} pointer can be obtained using
+ * ASensorManager_getDefaultSensor(),
+ * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
+ *
+ * This file provides a set of functions to access properties of a
+ * {@link ASensor}:
+ * - ASensor_getName()
+ * - ASensor_getVendor()
+ * - ASensor_getType()
+ * - ASensor_getResolution()
+ * - ASensor_getMinDelay()
+ * - ASensor_getFifoMaxEventCount()
+ * - ASensor_getFifoReservedEventCount()
+ * - ASensor_getStringType()
+ * - ASensor_getReportingMode()
+ * - ASensor_isWakeUpSensor()
+ */
 typedef struct ASensor ASensor;
+/**
+ * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
+ *
+ * This is used to define entry in {@link ASensorList} arrays.
+ */
 typedef ASensor const* ASensorRef;
+/**
+ * {@link ASensorList} is an array of reference to {@link ASensor}.
+ *
+ * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
+ */
 typedef ASensorRef const* ASensorList;
 
 /*****************************************************************************/
 
-/*
+/**
  * Get a reference to the sensor manager. ASensorManager is a singleton.
  *
  * Example:
@@ -203,31 +319,35 @@
 ASensorManager* ASensorManager_getInstance();
 
 
-/*
+/**
  * Returns the list of available sensors.
  */
 int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
 
-/*
+/**
  * Returns the default sensor for the given type, or NULL if no sensor
  * of that type exists.
  */
 ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
 
-/*
+/**
  * Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
  * of this type and wakeUp properties exists.
  */
 ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type,
         bool wakeUp);
 
-/*
+/**
  * Creates a new sensor event queue and associate it with a looper.
+ *
+ * "ident" is a identifier for the events that will be returned when
+ * calling ALooper_pollOnce(). The identifier must be >= 0, or
+ * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
  */
 ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
         ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
 
-/*
+/**
  * Destroys the event queue and free all resources associated to it.
  */
 int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
@@ -235,17 +355,17 @@
 
 /*****************************************************************************/
 
-/*
+/**
  * Enable the selected sensor. Returns a negative error code on failure.
  */
 int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
 
-/*
+/**
  * Disable the selected sensor. Returns a negative error code on failure.
  */
 int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
 
-/*
+/**
  * Sets the delivery rate of events in microseconds for the given sensor.
  * Note that this is a hint only, generally event will arrive at a higher
  * rate. It is an error to set a rate inferior to the value returned by
@@ -254,14 +374,14 @@
  */
 int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
 
-/*
+/**
  * Returns true if there are one or more events available in the
  * sensor queue.  Returns 1 if the queue has events; 0 if
  * it does not have events; and a negative value if there is an error.
  */
 int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
 
-/*
+/**
  * Returns the next available events from the queue.  Returns a negative
  * value if no events are available or an error has occurred, otherwise
  * the number of events returned.
@@ -280,55 +400,55 @@
 
 /*****************************************************************************/
 
-/*
+/**
  * Returns this sensor's name (non localized)
  */
 const char* ASensor_getName(ASensor const* sensor);
 
-/*
+/**
  * Returns this sensor's vendor's name (non localized)
  */
 const char* ASensor_getVendor(ASensor const* sensor);
 
-/*
+/**
  * Return this sensor's type
  */
 int ASensor_getType(ASensor const* sensor);
 
-/*
+/**
  * Returns this sensors's resolution
  */
 float ASensor_getResolution(ASensor const* sensor);
 
-/*
+/**
  * Returns the minimum delay allowed between events in microseconds.
  * A value of zero means that this sensor doesn't report events at a
  * constant rate, but rather only when a new data is available.
  */
 int ASensor_getMinDelay(ASensor const* sensor);
 
-/*
+/**
  * Returns the maximum size of batches for this sensor. Batches will often be
  * smaller, as the hardware fifo might be used for other sensors.
  */
 int ASensor_getFifoMaxEventCount(ASensor const* sensor);
 
-/*
+/**
  * Returns the hardware batch fifo size reserved to this sensor.
  */
 int ASensor_getFifoReservedEventCount(ASensor const* sensor);
 
-/*
+/**
  * Returns this sensor's string type.
  */
 const char* ASensor_getStringType(ASensor const* sensor);
 
-/*
+/**
  * Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
  */
 int ASensor_getReportingMode(ASensor const* sensor);
 
-/*
+/**
  * Returns true if this is a wake up sensor, false otherwise.
  */
 bool ASensor_isWakeUpSensor(ASensor const* sensor);
@@ -338,3 +458,5 @@
 #endif
 
 #endif // ANDROID_SENSOR_H
+
+/** @} */