[sensors] Format, wording and naming changes
* replace all "should" description with more precise wording.
* replace "aidl" name in parameter to avoid confusion.
* reformat files and method description.
Test: m -j32
Change-Id: Id1129b816b3c364c76f0a24fabba1e1418dbd8db
diff --git a/sensors/1.0/ISensors.hal b/sensors/1.0/ISensors.hal
index bb57f73..a60cc10 100644
--- a/sensors/1.0/ISensors.hal
+++ b/sensors/1.0/ISensors.hal
@@ -23,7 +23,7 @@
getSensorsList() generates (vec<SensorInfo> list);
/**
- * Place the module in a specific mode. The following modes are defined
+ * Place the module in a specific mode. The following modes are defined
*
* SENSOR_HAL_NORMAL_MODE - Normal operation. Default state of the module.
*
@@ -39,25 +39,28 @@
/* Activate/de-activate one sensor.
*
- * sensorHandle is the handle of the sensor to change.
- * enabled set to true to enable, or false to disable the sensor.
- *
* After sensor de-activation, existing sensor events that have not
- * been picked up by poll() should be abandoned immediately so that
+ * been picked up by poll() must be abandoned immediately so that
* subsequent activation will not get stale sensor events (events
* that are generated prior to the latter activation).
*
- * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
+ * @param sensorHandle is the handle of the sensor to change.
+ * @param enabled set to true to enable, or false to disable the sensor.
+ *
+ * @return result OK on success, BAD_VALUE if sensorHandle is invalid.
*/
activate(int32_t sensorHandle, bool enabled) generates (Result result);
/**
* Set the sampling period in nanoseconds for a given sensor.
+ *
* If samplingPeriodNs > maxDelay it will be truncated to
* maxDelay and if samplingPeriodNs < minDelay it will be
* replaced by minDelay.
*
- * Returns OK on success, BAD_VALUE if sensorHandle is invalid.
+ * @param sensorHandle handle of sensor to be changed.
+ * @param samplngPeriodNs specified sampling period in nanoseconds.
+ * @return result OK on success, BAD_VALUE if sensorHandle is invalid.
*/
setDelay(int32_t sensorHandle, int64_t samplingPeriodNs)
generates (Result result);
@@ -69,10 +72,15 @@
* Additionally a vector of SensorInfos is returned for any dynamic sensors
* connected as notified by returned events of type DYNAMIC_SENSOR_META.
*
- * This function should block if there is no sensor event
- * available when being called.
+ * If there is no sensor event when this function is being called, block
+ * until there are sensor events available.
*
- * Returns OK on success or BAD_VALUE if maxCount <= 0.
+ * @param maxCount max number of samples can be returned.
+ * @return result OK on success or BAD_VALUE if maxCount <= 0.
+ * @return data vector of Event contains sensor events.
+ * @return dynamicSensorsAdded vector of SensorInfo contains dynamic sensor
+ * added. Each element corresponds to a dynamic sensor meta events
+ * in data.
*/
poll(int32_t maxCount)
generates (
@@ -90,7 +98,11 @@
* See the Batching sensor results page for details:
* http://source.android.com/devices/sensors/batching.html
*
- * Returns OK on success, BAD_VALUE if any parameters are invalid.
+ * @param sensorHandle handle of sensor to be changed.
+ * @param samplingPeriodNs specifies sensor sample period in nanoseconds.
+ * @param maxReportLatencyNs allowed delay time before an event is sampled
+ * to time of report.
+ * @return result OK on success, BAD_VALUE if any parameters are invalid.
*/
batch(int32_t sensorHandle,
int32_t flags,
@@ -98,17 +110,19 @@
int64_t maxReportLatencyNs) generates (Result result);
/*
+ * Trigger a flush of internal FIFO.
+ *
* Flush adds a FLUSH_COMPLETE metadata event to the end of the "batch mode"
- * FIFO for the specified sensor and flushes the FIFO.
- * If the FIFO is empty or if the sensor doesn't support batching
- * (FIFO size zero), it should return SUCCESS along with a trivial
- * FLUSH_COMPLETE event added to the event stream.
- * This applies to all sensors other than one-shot sensors.
- * If the sensor is a one-shot sensor, flush must return BAD_VALUE and not
- * generate any flush complete metadata.
- * If the sensor is not active at the time flush() is called, flush() should
- * return BAD_VALUE.
- * Returns OK on success and BAD_VALUE if sensorHandle is invalid.
+ * FIFO for the specified sensor and flushes the FIFO. If the FIFO is empty
+ * or if the sensor doesn't support batching (FIFO size zero), return
+ * SUCCESS and add a trivial FLUSH_COMPLETE event added to the event stream.
+ * This applies to all sensors other than one-shot sensors. If the sensor
+ * is a one-shot sensor, flush must return BAD_VALUE and not generate any
+ * flush complete metadata. If the sensor is not active at the time flush()
+ * is called, flush() return BAD_VALUE.
+ *
+ * @param sensorHandle handle of sensor to be flushed.
+ * @return result OK on success and BAD_VALUE if sensorHandle is invalid.
*/
flush(int32_t sensorHandle) generates (Result result);
@@ -145,8 +159,8 @@
* Unregister direct report channel.
*
* Unregister a direct channel previously registered using
- * registerDirectChannel. If there is still active sensor report configured
- * in the direct channel, HAL should remove them.
+ * registerDirectChannel, and remove all active sensor report configured in
+ * still active sensor report configured in the direct channel.
*
* @param channelHandle handle of direct channel to be unregistered.
* @return result OK if direct report is supported; INVALID_OPERATION