enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

eeze: Give the eeze_sensor doxygen an overhaul. 

Wrap at 80 chars, fix some typos and add more descriptions.

SVN revision: 80070
This commit is contained in:
Stefan Schmidt 2012-12-03 14:44:33 +00:00
parent 4f48fd72d0
commit a423b298b8
1 changed files with 55 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
legacy/eeze/src/lib/Eeze_Sensor.h
View File

@ -21,13 +21,14 @@
* @file Eeze_Sensor.h
* @brief Sensor information
*
* Eeze sensor functions allow you to gather sensor information from different sensor sources
* available on the hardware. It supports a plugin architecture to support different hardware
* platforms and devices. These plugins can be loaded at runtime to allow support for a specific
* set of hardware or platform.
* Eeze sensor functions allow you to gather sensor information from different
* sensor sources available on the hardware. It supports a plugin architecture
* to support different hardware platforms and devices. These plugins can be
* loaded at runtime to allow support for a specific set of hardware or
* platform.
*
* Right now we have support for the Tizen sensor framework as well as a simple fake plugin to be
* used as a test harness for developing.
* Right now we have support for the Tizen sensor framework as well as a simple
* fake plugin to be used as a test harness for developing.
*
* @since 1.8
*
@ -37,10 +38,12 @@
/**
* @enum Eeze_Sensor_Type
* @since 1.8
*
* All sensor types known by Eeze Sensor. This list of types include real physical types like
* proximity or light as well as "aggregated" types like facedown or doubletap.
* All sensor types known by Eeze Sensor. This list of types include real
* physical types like proximity or light as well as "aggregated" types like
* facedown or doubletap.
*
* @since 1.8
*/
typedef enum
{
@ -65,9 +68,9 @@ typedef enum
* @defgroup Sensor_Events Available eeze sensor events
* @brief Sensor events that are emitted from the library as ecore events
*
* Event types used to register #ecore_event_handler on. These events are used for
* #eeze_sensor_async_read to deliver read out data. It is also used for generated events like
* facedown or shake.
* Event types used to register #ecore_event_handler on. These events are used
* for #eeze_sensor_async_read to deliver read out data. It is also used for
* generated events like facedown or shake.
*
* @since 1.8
* @{
@ -90,14 +93,14 @@ EAPI int EEZE_SENSOR_EVENT_TEMPERATURE;
/**
* @typedef Eeze_Sensor_Obj;
*
* Object for a sensor type. Keeps information about the type and holds the data for the accessor
* functions. As this information gets also updated by asynchronous reads it might be a good idea
* to check the timestamp value to see when the data has been updated. The timestamp is given in
* microseconds.
* Object for a sensor type. Keeps information about the type and holds the
* data for the accessor functions. As this information gets also updated by
* asynchronous reads it might be a good idea to check the timestamp value to
* see when the data has been updated. The timestamp is given in microseconds.
*
* You are not supposed to access the raw data values from here but use the getter functions for it.
* Using the raw values from this struct might break your applications later if the internal
* structure changes.
* You are not supposed to access the raw data values from here but use the
* getter functions for it. Using the raw values from this struct might break
* your applications later if the internal structure changes.
*
* @since 1.8
*/
@ -119,12 +122,14 @@ extern "C" {
* @param type Sensor type to create object from.
* @return Sensor object for the given type.
*
* Takes the sensor type and create an object for it to operate on. During this it also does an
* initial sensor data read to fill the sensor data into the object.
* The #eeze_sensor_free function must be used to destroy the object and release its memory.
* Takes the sensor type and create an object for it to operate on. During this
* it also does an initial sensor data read to fill the sensor data into the
* object. The #eeze_sensor_free function must be used to destroy the object
* and release its memory.
*
* For every sensor type you want to work with this is the first thing you have to do. Create the
* object from the type and everything else the operates on this object.
* For every sensor type you want to work with this is the first thing you have
* to do. Create the object from the type and everything else the operates on
* this object.
*
* @since 1.8
*/
@ -146,8 +151,8 @@ EAPI void eeze_sensor_free(Eeze_Sensor_Obj *sens);
* @param accuracy Pointer to write accuracy value into.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* Access function to get the accuracy property from the sensor object. The accuracy value can have
* the following values and meaning:
* Access function to get the accuracy property from the sensor object. The
* accuracy value can have the following values and meaning:
* -1 Undefined accuracy
* 0 Bad accurancy
* 1 Normal accuracy
@ -166,8 +171,9 @@ EAPI Eina_Bool eeze_sensor_accuracy_get(Eeze_Sensor_Obj *sens, int *accuracy);
* @param z Pointer to write third data property value into.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* Access function to get all three data properties from the sensor object. This is used for sensor
* types that offer all three values. Like accelerometer and magnetic.
* Access function to get all three data properties from the sensor object.
* This is used for sensor types that offer all three values. Like accelerometer
* and magnetic.
*
* @since 1.8
*/
@ -180,8 +186,8 @@ EAPI Eina_Bool eeze_sensor_xyz_get(Eeze_Sensor_Obj *sens, float *x, float *y, fl
* @param y Pointer to write second data property value into.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* Access function to get the first two data properties from the sensor object. This is used for
* sensor types that offer two values. Like panning.
* Access function to get the first two data properties from the sensor object.
* This is used for sensor types that offer two values. Like panning.
*
* @since 1.8
*/
@ -193,8 +199,8 @@ EAPI Eina_Bool eeze_sensor_xy_get(Eeze_Sensor_Obj *sens, float *x, float *y);
* @param x Pointer to write first data property value into.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* Access function to get the first data property from the sensor object. This is used for sensor
* types that only offer one value. Like light or proximity.
* Access function to get the first data property from the sensor object. This
* is used for sensor types that only offer one value. Like light or proximity.
*
* @since 1.8
*/
@ -206,8 +212,9 @@ EAPI Eina_Bool eeze_sensor_x_get(Eeze_Sensor_Obj *sens, float *x);
* @param timestamp Pointer to write timestamp value into.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* Access function to get the timestamp property from the sensor object. It allows you to determine
* if the values have been updated since the last time you requested them.
* Access function to get the timestamp property from the sensor object. It
* allows you to determine if the values have been updated since the last time
* you requested them.
*
* @since 1.8
*/
@ -218,9 +225,10 @@ EAPI Eina_Bool eeze_sensor_timestamp_get(Eeze_Sensor_Obj *sens, unsigned long lo
* @param sens Sensor object to operate on.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* This function reads sensor data from the device and fills the sensor object with the data. This
* call is synchronous and blocks until the data is read out and updated in the sensor object.
* For simple applications this is fine and the easiest way to use the API.
* This function reads sensor data from the device and fills the sensor object
* with the data. This call is synchronous and blocks until the data is read out
* and updated in the sensor object. For simple applications this is fine and
* the easiest way to use the API.
*
* @since 1.8
*/
@ -232,9 +240,10 @@ EAPI Eina_Bool eeze_sensor_read(Eeze_Sensor_Obj *sens);
* @param user_data Data to pass to the callback function.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* This function reads sensor data from the device and fills the sensor object with the data. The
* read is done asynchronously and thus does not block after calling. Instead the given callback
* function is called once the read is finished and the object filled.
* This function reads sensor data from the device and fills the sensor object
* with the data. The read is done asynchronously and thus does not block after
* calling. Instead the given callback function is called once the read is
* finished and the object filled.
*
* @since 1.8
*/
@ -253,6 +262,9 @@ EAPI Eeze_Sensor_Obj *eeze_sensor_obj_get(Eeze_Sensor_Type type);
* @brief Initialize the Eeze sensor subsystem.
* @return EINA_TRUE for success and EINA_FALSE for failure
*
* This function must be called before using any of the Eeze_Sensor
* functionality to make sure the subsystem is setup correctly for usage.
*
* @since 1.8
*/
Eina_Bool eeze_sensor_init(void);
@ -260,6 +272,9 @@ Eina_Bool eeze_sensor_init(void);
/**
* @brief Clean up and shutdown the Eeze sensor subsystem.
*
* This function must be called when now longer using Eeze_Sensor to allow the
* subsystem to shutdown cleanly.
*
* @since 1.8
*/
void eeze_sensor_shutdown(void);