From a423b298b8bec5e21fffd91f275a3c2aa3994cea Mon Sep 17 00:00:00 2001 From: Stefan Schmidt Date: Mon, 3 Dec 2012 14:44:33 +0000 Subject: [PATCH] eeze: Give the eeze_sensor doxygen an overhaul. Wrap at 80 chars, fix some typos and add more descriptions. SVN revision: 80070 --- legacy/eeze/src/lib/Eeze_Sensor.h | 95 ++++++++++++++++++------------- 1 file changed, 55 insertions(+), 40 deletions(-) diff --git a/legacy/eeze/src/lib/Eeze_Sensor.h b/legacy/eeze/src/lib/Eeze_Sensor.h index ffc6266e88..6a6e85c86b 100644 --- a/legacy/eeze/src/lib/Eeze_Sensor.h +++ b/legacy/eeze/src/lib/Eeze_Sensor.h @@ -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);