Elaborate doxygen description of header file

Change-Id: I6479cf326971cea7a48f38a9b19c5427d716a9da
Signed-off-by: Youngjae Cho <y0.cho@samsung.com>

diff --git a/include/runtime_info.h b/include/runtime_info.h
index 88aaaeb9d847c30272035b86f3b7d256e3ac8ca3..39592be2d67ffe2a6240e2e77aae09bb72d5f107 100644 (file)
--- a/include/runtime_info.h
+++ b/include/runtime_info.h
@@ -199,7 +199,10 @@ int runtime_info_get_value_string(runtime_info_key_e key, char **value);
 
 /**
  * @brief        Registers a change event callback for given runtime information key.
+ * @details      Only the last registered callback will be operational if it is called multiple
+ *               times on a same key. That is, it replaces previously registered one, if any.
  * @since_tizen  2.3
+ * @remarks  You must release @a callback using runtime_info_unset_changed_cb().
  *
  * @param[in] key        The runtime information type
  * @param[in] callback   The callback function to invoke
@@ -220,7 +223,8 @@ int runtime_info_set_changed_cb(runtime_info_key_e key, runtime_info_changed_cb
 
 
 /**
- * @brief        Unregisters the callback function.
+ * @brief        Unregisters the callback function registered by runtime_info_set_changed_cb().
+ * @details      Unregisters the callback function registered by runtime_info_set_changed_cb() on the key.
  * @since_tizen  2.3
  *
  * @param[in] key  The runtime information type
@@ -249,7 +253,8 @@ typedef struct {
 
 
 /**
- * @brief        Gets system memory information.
+ * @brief        Gets system memory information in the form of runtime_memory_info_s.
+ * @details      The information is collected from /proc/meminfo.
  * @since_tizen  2.4
  *
  * @param[out] info  The system memory information structure
@@ -281,7 +286,8 @@ typedef struct {
 
 
 /**
- * @brief        Gets memory information per process.
+ * @brief        Gets memory information per process in the form of process_memory_info_s.
+ * @details      The information is collected from /proc/[pid]/stat and /proc/[pid]/smaps.
  * @since_tizen  2.4
  *
  * @privlevel  public
@@ -320,7 +326,8 @@ typedef struct {
 
 
 /**
- * @brief        Gets CPU information.
+ * @brief        Gets CPU usgae information in the form of runtime_cpu_usage_s.
+ * @details      The information is collected from /proc/stat.
  * @since_tizen  2.4
  *
  * @param[out] usage  The CPU usage structure
@@ -347,7 +354,8 @@ typedef struct {
 
 
 /**
- * @brief        Gets CPU usage per process.
+ * @brief        Gets CPU usage in the form of process_cpu_usage_s.
+ * @details      The information is collected from /proc/[pid]/stat.
  * @since_tizen  2.4
  *
  * @privlevel  public
@@ -374,7 +382,8 @@ int runtime_info_get_process_cpu_usage(int *pid, int size, process_cpu_usage_s *
 
 
 /**
- * @brief        Gets the number of processors.
+ * @brief        Gets the total number of processors including both online and offline.
+ * @details      The information is collected from /sys/devices/system/cpu/possible.
  * @since_tizen  3.0
  *
  * @param[out] num_core  The number of whole processors
@@ -389,7 +398,8 @@ int runtime_info_get_processor_count(int *num_core);
 
 
 /**
- * @brief        Gets the current frequency of processor.
+ * @brief        Gets the current frequency of a specific processor.
+ * @details      The information is collected from /sys/devices/system/cpu/cpu[idx]/cpufreq/scaling_cur_freq.
  * @since_tizen  3.0
  *
  * @param[in]  core_idx  The index (from 0) of CPU core that you want to know the frequency
@@ -406,7 +416,8 @@ int runtime_info_get_processor_current_frequency(int core_idx, int *cpu_freq);
 
 
 /**
- * @brief        Gets the max frequency of processor.
+ * @brief        Gets the maximum frequency of a specific processor.
+ * @details      The information is collected from /sys/devices/system/cpu/cpu[idx]/cpufreq/scaling_max_freq.
  * @since_tizen  3.0
  *
  * @param[in]  core_idx  The index (from 0) of CPU core that you want to know the frequency
@@ -423,7 +434,8 @@ int runtime_info_get_processor_max_frequency(int core_idx, int *cpu_freq);
 
 
 /**
- * @brief        Gets the physical memory size.
+ * @brief        Gets the total physical memory size in kibibyte(KiB).
+ * @details      The information is collected from /proc/zoneinfo.
  * @since_tizen  4.0
  *
  * @param[out] size  Physical memory size (KiB)
@@ -445,7 +457,9 @@ typedef struct app_usages_s *app_usage_h;
 
 
 /**
- * @brief        Frees an app usage handle.
+ * @brief        Destroy app_usage_h that won't be used anymore.
+ * @details      Destroy app_usage_h acquired by functions runtime_info_get_all_apps_memory_usage()
+ *               or runtime_info_get_all_apps_cpu_rate().
  * @since_tizen  4.0
  *
  * @param[in] handle  App usage handle to free
@@ -454,12 +468,16 @@ typedef struct app_usages_s *app_usage_h;
  *          otherwise a negative error value
  * @retval #RUNTIME_INFO_ERROR_NONE               Successful
  * @retval #RUNTIME_INFO_ERROR_INVALID_PARAMETER  Invalid parameter
+ *
+ * @see  runtime_info_get_all_apps_memory_usage()
+ * @see  runtime_info_get_all_apps_cpu_rate()
  */
 int runtime_info_app_usage_destroy(app_usage_h handle);
 
 
 /**
- * @brief        Gets the app count from an app usage handle.
+ * @brief        Gets the number of applications that app_usage_h has retrieved.
+ * @details      Gets only applications that are managed by <a href=""https://docs.tizen.org/application/native/guides/app-management/app-manager/>Application Manager</a>.
  * @since_tizen  4.0
  *
  * @param[in]  handle  The app usage handle
@@ -477,7 +495,8 @@ int runtime_info_app_usage_get_count(app_usage_h handle, int *count);
 
 
 /**
- * @brief        Gets the app ID from an app usage handle.
+ * @brief        Gets an application ID by index from an app_usage_h.
+ * @details      Gets only applications that are managed by <a href=""https://docs.tizen.org/application/native/guides/app-management/app-manager/>Application Manager</a>.
  * @since_tizen  4.0
  *
  * @remarks  You must release @a appid using free().
@@ -499,7 +518,10 @@ int runtime_info_app_usage_get_appid(app_usage_h handle, int index, char **appid
 
 
 /**
- * @brief        Gets resource usage from an app usage handle.
+ * @brief        Gets resource usage of an application by index from an app_usage_h.
+ * @details      Counts memory that is exclusively used by an application. That is, it doesn't
+ *               count shared memory of an application such as file or shared library, etc.
+ *               Gets only applications that are managed by <a href=""https://docs.tizen.org/application/native/guides/app-management/app-manager/>Application Manager</a>.
  * @since_tizen  4.0
  *
  * @remarks  The meaning of @a usage depends on which function was used to create @a handle.
@@ -521,7 +543,10 @@ int runtime_info_app_usage_get_usage(app_usage_h handle, int index, unsigned int
 
 
 /**
- * @brief        Gets memory usage of all apps.
+ * @brief        Gets memory usage of all applications in kilobyte into app_usage_h.
+ * @details      Counts memory that is exclusively used by an application. That is, it doesn't
+ *               count shared memory of an application such as file or shared library, etc.
+ *               Gets only applications that are managed by <a href=""https://docs.tizen.org/application/native/guides/app-management/app-manager/>Application Manager</a>.
  * @since_tizen  4.0
  *
  * @privlevel  public
@@ -570,7 +595,9 @@ int runtime_info_get_all_apps_memory_usage(app_usage_h *usage);
 
 
 /**
- * @brief        Gets CPU rate of all apps.
+ * @brief        Gets CPU rate of all applications in kilobyte into app_usage_h.
+ * @detail       The information is collected from /proc/[pid]/stat.
+ *               Gets only applications that are managed by <a href=""https://docs.tizen.org/application/native/guides/app-management/app-manager/>Application Manager</a>.
  * @since_tizen  4.0
  *
  * @privlevel  public