battery_monitor: Update description of battery_monitor

Update description of battery_monitor in each tags.

Change-Id: Id68cf7fc81eed117a58a5e6f6ddd5db77a479794
Signed-off-by: Unsung Lee <unsung.lee@samsung.com>

diff --git a/include/battery_monitor.h b/include/battery_monitor.h
index 8b4830bc0403051f12d52811fad9461899723f7d..c0a86e8cf0d6fec6a87c635db4a284ee4e181a93 100644 (file)
--- a/include/battery_monitor.h
+++ b/include/battery_monitor.h
@@ -70,53 +70,71 @@ typedef struct battery_monitor_total_consumption_s* battery_usage_data_h;
 
 /**
  * @brief  Destroys the Battery Consumption handle and releases all its resources.
+ * @details Releases all resources in battery_monitor_total_consumption_s structure using free().
  * @since_tizen  5.5
- *
+ * @remarks User cannot access resources in @a result after completion of the call.
  * @param[in] result  Battery usage consumption handle for the application
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
  * @retval #BATTERY_MONITOR_ERROR_NOT_SUPPORTED         Feature Not Supported
  * @retval #BATTERY_MONITOR_ERROR_INVALID_PARAMETER     Invalid Parameter
+ * @see battery_monitor_get_power_usage_by_app_for_all_resources()
+ * @code
+ *      battery_usage_data_h data_handle = NULL;
+ *      battery_monitor_get_power_usage_by_app_for_all_resources("org.test.app",
+ *                     (time_t)100, (time_t)1000, &data_handle);
+ *      // Using battery info in data_handle
+ *
+ *      // Release battery info in data_handle
+ *      battery_monitor_battery_usage_data_destroy(data_handle);
+ * @endcode
  */
 int battery_monitor_battery_usage_data_destroy(battery_usage_data_h result);
 
 /**
  * @brief  Gets the battery consumption in mAh (milli-Ampere hour) for specific resource from available data usage handle.
+ * @details Retrives the battery comsumption for specific resource defined in battery_monitor_resource_id_e
+ *          and change battery consumption in mAh.
  * @since_tizen  5.5
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/systemmonitor
- *
+ * @remarks Must be executed after calling battery_monitor_get_power_usage_by_app_for_all_resources().
  * @param[in] result  Battery consumption data usage handle for the application
  * @param[in] resource  Identifier of resource type. BLE, WiFi, CPU etc
  * @param[out] usage  Battery consumption in mAh for @a resource
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
  * @retval #BATTERY_MONITOR_ERROR_NOT_SUPPORTED         Feature Not Supported
  * @retval #BATTERY_MONITOR_ERROR_PERMISSION_DENIED     Permission Denied
  * @retval #BATTERY_MONITOR_ERROR_INVALID_PARAMETER     Invalid Parameter
- *
  * @pre call battery_monitor_get_power_usage_by_app_for_all_resources() to get data handle
+ * @code
+ *      double usage;
+ *      battery_usage_data_h data_handle = NULL;
+ *      battery_monitor_get_power_usage_by_app_for_all_resources("org.test.app",
+ *                     (time_t)100, (time_t)1000, &data_handle);
+ *
+ *      battery_monitor_usage_data_get_power_usage_per_resource(data_handle,
+ *                BATTERY_MONITOR_RESOURCE_ID_BLE, &usage)
+ * @endcode
  */
 int battery_monitor_usage_data_get_power_usage_per_resource(battery_usage_data_h result, battery_monitor_resource_id_e resource, double* usage);
 
 /**
- * @brief  Gets the #battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour) by the specified application in custom interval.
- *         Data within the last 7 days can be retrieved.
+ * @brief  Gets the #battery_usage_data_h with battery consumption values in mAh (milli-Ampere hour).
+ * @details Retrieves the battery consumption used by a specific application for a certain period of time,
+ *          based on each resource declared in battery_usage_data_h.
  * @since_tizen  5.5
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/systemmonitor
- *
- * @remarks  The @a result handle should be released using battery_monitor_battery_usage_data_destroy().
- *
+ * @remarks  The @a result handle should be released using battery_monitor_battery_usage_data_destroy(). \n
+ *           Data within up to the last seven days can be retrieved.
  * @param[in] appid  Application ID of the application for which battery usage is required
  * @param[in] from Start Time for data in Epoch Time (in seconds)
  * @param[in] to End Time for data in Epoch Time (in seconds)
  * @param[out] result  Battery consumption data handle for the application
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
@@ -127,24 +145,25 @@ int battery_monitor_usage_data_get_power_usage_per_resource(battery_usage_data_h
  * @retval #BATTERY_MONITOR_ERROR_DB_FAILED             DB operation failed
  * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND      Record Not found
  * @retval #BATTERY_MONITOR_ERROR_INTERNAL              Internal Error
- *
  * @see battery_monitor_usage_data_get_power_usage_per_resource()
+ * @see battery_monitor_get_power_usage_by_app()
+ * @see battery_monitor_get_power_usage_by_resource()
  */
 int battery_monitor_get_power_usage_by_app_for_all_resources(const char* appid, time_t from, time_t to, battery_usage_data_h* result);
 
 /**
- * @brief  Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource for the given application in custom interval.
- *         Data within the last 7 days can be retrieved.
+ * @brief  Gets the battery consumption in mAh (milli-Ampere hour) for the specific resource.
+ * @details Retrieves the battery consumption used by a specific application for a certain period of time,
+ *          based on a specific resource.
  * @since_tizen  5.5
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/systemmonitor
- *
+ * @remarks Data within up to the last seven days can be retrieved.
  * @param[in] appid  Application ID of the application for which battery usage is required
  * @param[in] resource  Identifier of resource type. BLE, WiFi, CPU etc
  * @param[in] from Start Time for data in Epoch Time (in seconds)
  * @param[in] to End Time for data in Epoch Time (in seconds)
  * @param[out] usage  Battery consumption in mAh for the application
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
@@ -155,21 +174,29 @@ int battery_monitor_get_power_usage_by_app_for_all_resources(const char* appid,
  * @retval #BATTERY_MONITOR_ERROR_DB_FAILED             DB operation failed
  * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND      Record Not found
  * @retval #BATTERY_MONITOR_ERROR_INTERNAL              Internal Error
+ * @see battery_monitor_get_power_usage_by_app_for_all_resources()
+ * @see battery_monitor_get_power_usage_by_app()
+ * @see battery_monitor_get_power_usage_by_resource()
+ * @code
+ *      double usage;
+ *      battery_monitor_get_power_usage_by_app_for_per_resource("org.test.app",
+ *                     BATTERY_MONITOR_RESOURCE_ID_BLE,
+ *                     (time_t)100, (time_t)1000, &usage);
+ * @endcode
  */
 int battery_monitor_get_power_usage_by_app_per_resource(const char* appid, battery_monitor_resource_id_e resource, time_t from, time_t to, double* usage);
 
 /**
- * @brief  Gets the total battery usage in mAh (milli-Ampere hour) by an application for certain time interval. Data within the last 7 days can be retrieved.
+ * @brief  Gets the total battery usage in mAh (milli-Ampere hour).
  * @details  This will be sum of all battery consumed by resources used by application.
  * @since_tizen  5.5
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/systemmonitor
- *
+ * @remarks Data within up to the last seven days can be retrieved.
  * @param[in] appid  Application ID of the application for which battery usage is required
  * @param[in] from Start Time for data in Epoch Time (in seconds)
  * @param[in] to End Time for data in Epoch Time (in seconds)
  * @param[out] usage  Battery consumption in mAh for the application
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
@@ -180,20 +207,28 @@ int battery_monitor_get_power_usage_by_app_per_resource(const char* appid, batte
  * @retval #BATTERY_MONITOR_ERROR_DB_FAILED             DB operation failed
  * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND      Record Not found
  * @retval #BATTERY_MONITOR_ERROR_INTERNAL              Internal Error
+ * @see battery_monitor_get_power_usage_by_app_for_all_resources()
+ * @see battery_monitor_get_power_usage_by_app_per_resource()
+ * @see battery_monitor_get_power_usage_by_resource()
+ * @code
+ *      double usage;
+ *      battery_monitor_get_power_usage_by_app("org.test.app",
+ *                     (time_t)100, (time_t)1000, &usage);
+ * @endcode
  */
 int battery_monitor_get_power_usage_by_app(const char* appid, time_t from, time_t to, double* usage);
 
 /**
- * @brief  Gets the battery usage in mAh (milli-Ampere hour) by a resource for certain time interval. Data within the last 7 days can be retrieved.
+ * @brief  Gets the battery usage in mAh (milli-Ampere hour) by a resource.
+ * @details Retrieves the battery consumption used by a specific resource for a certain period of time.
  * @since_tizen  5.5
  * @privlevel  public
  * @privilege  %http://tizen.org/privilege/systemmonitor
- *
+ * @remarks Data within up to the last seven days can be retrieved.
  * @param[in] resource  Resource identifier for which battery usage is requested
  * @param[in] from Start Time for data in Epoch Time (in seconds)
  * @param[in] to End Time for data in Epoch Time (in seconds)
  * @param[out] usage  Battery consumption in mAh (milli-Ampere hour) for resource
- *
  * @return  @c 0 on success,
  *          otherwise a negative error value
  * @retval #BATTERY_MONITOR_ERROR_NONE                  Successful
@@ -204,6 +239,14 @@ int battery_monitor_get_power_usage_by_app(const char* appid, time_t from, time_
  * @retval #BATTERY_MONITOR_ERROR_DB_FAILED             DB operation failed
  * @retval #BATTERY_MONITOR_ERROR_RECORD_NOT_FOUND      Record Not found
  * @retval #BATTERY_MONITOR_ERROR_INTERNAL              Internal Error
+ * @see battery_monitor_get_power_usage_by_app_for_all_resources()
+ * @see battery_monitor_get_power_usage_by_app_per_resource()
+ * @see battery_monitor_get_power_usage_by_app()
+ * @code
+ *      double usage;
+ *      battery_monitor_get_power_usage_by_app(BATTERY_MONITOR_RESOURCE_ID_BLE,
+ *                     (time_t)100, (time_t)1000, &usage);
+ * @endcode
  */
 int battery_monitor_get_power_usage_by_resource(battery_monitor_resource_id_e resource, time_t from, time_t to, double* usage);