sensor.h: Add remarks and example codes

Since there was no remarks about memory management(free or not) and
example codes for functions "sensor_get_default_sensor" and
"sensor_get_default_sensor_by_uri", they are added.

Change-Id: I561687553242d6d74db63ed528ff0ed1f7efa03f
Signed-off-by: SangYoun Kwak <sy.kwak@samsung.com>

diff --git a/include/sensor.h b/include/sensor.h
index f002be3..6738ca7 100644 (file)
--- a/include/sensor.h
+++ b/include/sensor.h
@@ -242,6 +242,7 @@ int sensor_is_wake_up(sensor_h sensor, bool *wakeup);
  *          #SENSOR_HRM, #SENSOR_HRM_LED_GREEN, #SENSOR_HRM_LED_IR, #SENSOR_HRM_LED_RED,
  *          #SENSOR_HUMAN_PEDOMETER, #SENSOR_HUMAN_SLEEP_MONITOR, #SENSOR_HUMAN_SLEEP_DETECTOR,
  *          and #SENSOR_HUMAN_STRESS_MONITOR.
+ * @remarks The @sensor should not be released.
  *
  * @param[in]  type     A sensor type to get the handle of its default sensor
  * @param[out] sensor   The sensor handle of the default sensor
@@ -254,6 +255,18 @@ int sensor_is_wake_up(sensor_h sensor, bool *wakeup);
  *
  * @see     sensor_get_default_sensor_by_uri()
  * @see     sensor_get_sensor_list()
+ *
+ * @par Example
+ * @code
+ * #include <sensor.h>
+ * ...
+ * int ret = 0;
+ * sensor_h sensor;
+ * ret = sensor_get_default_sensor(SENSOR_ACCELEROMETER, &sensor);
+ * if (ret != SENSOR_ERROR_NONE)
+ *     return ret;
+ * ...
+ * @endcode
  */
 int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor);
 
@@ -268,6 +281,7 @@ int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor);
  * @remarks Some sensor types are privileged. An application should have the privilege
  *          %http://tizen.org/privilege/healthinfo to get handles for the sensor URIs of @"healthinfo@" category.
  *          See \ref CAPI_SYSTEM_SENSOR_LISTENER_MODULE_URI to find the @"healthinfo@" category sensor URIs.
+ * @remarks The @sensor should not be released.
  *
  * @param[in]    uri      A sensor or a sensor type URI to get the handle of its default sensor
  * @param[out]   sensor   The default sensor handle
@@ -280,6 +294,18 @@ int sensor_get_default_sensor(sensor_type_e type, sensor_h *sensor);
  *
  * @see     sensor_get_default_sensor()
  * @see     sensor_get_sensor_list_by_uri()
+ *
+ * @par Example
+ * @code
+ * #include <sensor.h>
+ * ...
+ * int ret = 0;
+ * sensor_h sensor;
+ * ret = sensor_get_default_sensor_by_uri("http://tizen.org/sensor/general/accelerometer", &sensor);
+ * if (ret != SENSOR_ERROR_NONE)
+ *     return ret;
+ * ...
+ * @endcode
  */
 int sensor_get_default_sensor_by_uri(const char *uri, sensor_h *sensor);