Add 50+ char long @details sections to docs

Convert existing @remarks section where available,
since @details are mandatory and @remarks are not.

Change-Id: I340987ae39f33b3a5e3c03f21a38ad31de4601b0

diff --git a/doc/diagnostics_doc.h b/doc/diagnostics_doc.h
index af211b8709b5eec2da01aef846e71872553b362f..e09329ddd0bebab9d49bc2a0c9879b6cdcee355f 100644 (file)
--- a/doc/diagnostics_doc.h
+++ b/doc/diagnostics_doc.h
@@ -18,6 +18,7 @@
  * @ingroup   CAPI_SYSTEM_FRAMEWORK
  * @defgroup  CAPI_SYSTEM_DIAGNOSTICS_MODULE Diagnostics
  * @brief     The @ref CAPI_SYSTEM_DIAGNOSTICS_MODULE API provides functions to send and receive diagnostic events and data from other applications/services.
+ * @details   The @ref CAPI_SYSTEM_DIAGNOSTICS_MODULE API provides functions to send and receive diagnostic events and data from other applications/services.
  *
  * @section   CAPI_SYSTEM_DIAGNOSTICS_MODULE_HEADER Required Header
  *            \#include <diagnostics.h>

diff --git a/include/diagnostics.h b/include/diagnostics.h
index 42ec85daaaf7f33c81a98330027306bdb7314f8e..4070ff25a2c19516abf981f425383dd561f286ce 100644 (file)
--- a/include/diagnostics.h
+++ b/include/diagnostics.h
@@ -34,18 +34,21 @@ extern "C" {
 
 /**
  * @brief An opaque handle to a system diagnostics context object.
+ * @details The diagnostics context is provided in data event callbacks.
  * @since_tizen 6.0
  */
 typedef void* diagnostics_ctx_h;
 
 /**
  * @brief An opaque handle to a system diagnostics data object.
+ * @details A single piece of diagnostics data, to be read or written to.
  * @since_tizen 6.0
  */
 typedef void* diagnostics_data_h;
 
 /**
  * @brief Enumeration for error codes returned by the diagnostics API.
+ * @details Most diagnostics API functions may return some of these values to indicate specific errors.
  * @since_tizen 6.0
  */
 typedef enum {
@@ -63,7 +66,7 @@ typedef enum {
 /**
  * @brief Notification callback fired when new diagnostics event arrives.
  * @since_tizen 6.0
- * @remarks @a ctx should be released with diagnostics_destroy().
+ * @details @a ctx should be released with diagnostics_destroy() after use.
  *
  * @param[in] ctx Diagnostics context handle
  * @param[in] user_data The user data passed from the callback registration function
@@ -73,7 +76,7 @@ typedef void(*diagnostics_notification_cb)(diagnostics_ctx_h ctx, void *user_dat
 /**
  * @brief Request callback fired when someone requests diagnostics data.
  * @since_tizen 6.5
- * @remarks @a data should be released with diagnostics_data_destroy().
+ * @details @a data should be released with diagnostics_data_destroy().
  *
  * @param[in] data Diagnostics data handle
  * @param[in] params Array of request's parameters \n
@@ -91,7 +94,7 @@ typedef void (*diagnostics_request_cb)(diagnostics_data_h data, char **params, i
 /**
  * @brief Sets the callback for diagnostics event notification.
  * @since_tizen 6.0
- * @remarks This function is dedicated to diagnostic information subscribers.
+ * @details This function is dedicated to diagnostic information subscribers.
  *
  * @param[in] callback A callback function to set
  * @param[in] user_data The user data to be passed to the callback function
@@ -131,7 +134,7 @@ API int diagnostics_set_notification_cb(diagnostics_notification_cb callback, vo
 /**
  * @brief Unsets the callback for diagnostics event notification.
  * @since_tizen 6.0
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * It clears all the events added with diagnostics_subscribe_event().
  *
  * @return 0 on success, otherwise a negative error value
@@ -147,7 +150,7 @@ API int diagnostics_unset_notification_cb(void);
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * It is permitted only to an app signed by platform level certificates.
  *
  * @param[in] event_name Event name \n
@@ -171,7 +174,7 @@ API int diagnostics_subscribe_event(const char *event_name, const char *client_i
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information providers. \n
+ * @details This function is dedicated to diagnostic information providers. \n
  * It is permitted only to an app signed by platform level certificates.
  *
  * @param[in] callback A callback function to set
@@ -223,7 +226,7 @@ API int diagnostics_set_data_request_cb(diagnostics_request_cb callback, void *u
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information providers. \n
+ * @details This function is dedicated to diagnostic information providers. \n
  * It is permitted only to an app signed by platform level certificates.
  *
  * @return 0 on success, otherwise a negative error value
@@ -240,7 +243,7 @@ API int diagnostics_unset_data_request_cb(void);
  * @since_tizen 6.0
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * It is permitted only to an app signed by platform level certificates. \n
  * @a data should be released with diagnostics_data_destroy().
  *
@@ -291,7 +294,7 @@ API int diagnostics_request_client_data(const char *client_id, const char **para
  * @since_tizen 6.0
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * It is permitted only to an app signed by platform level certificates. \n
  * @a data should be released with diagnostics_data_destroy(). \n
  * The difference between this function and diagnostics_request_client_data() is that
@@ -334,7 +337,7 @@ API int diagnostics_get_data(diagnostics_ctx_h ctx, const char **params, int par
 /**
  * @brief Gets a file descriptor for custom diagnostics data handling.
  * @since_tizen 6.5
- * @remarks This function provides a file descriptor to read/write diagnostic data in a custom way
+ * @details This function provides a file descriptor to read/write diagnostic data in a custom way
  * instead of using our diagnostics_data_read() and diagnostics_data_write() functions. \n
  * Moreover, keep in mind that reading is allowed for diagnostic data subscribers and writing is allowed for providers.
  * @param[in] data Diagnostics data handle
@@ -350,7 +353,7 @@ API int diagnostics_data_get_fd(diagnostics_data_h data, int *fd);
 /**
  * @brief Perform a single iteration of reading diagnostics data.
  * @since_tizen 6.0
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * It is intended for use in loop until EOF is reached. EOF is when @a bytes_read == 0 and function returns #DIAGNOSTICS_ERROR_NONE.
  *
  * @param[in] data Diagnostics data handle
@@ -373,7 +376,7 @@ API int diagnostics_data_read(diagnostics_data_h data, void *buf, size_t count,
 /**
  * @brief Perform a single iteration of writing diagnostics data.
  * @since_tizen 6.5
- * @remarks This function is dedicated to diagnostic information providers. \n
+ * @details This function is dedicated to diagnostic information providers. \n
  * Data is being written to the special file descriptor and then copied to the diagnostic information subscriber's endpoint.
  *
  * @param[in] data Diagnostics data handle
@@ -397,7 +400,7 @@ API int diagnostics_data_write(diagnostics_data_h data, const void *buf, size_t
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
- * @remarks This function is dedicated to diagnostic information providers. \n
+ * @details This function is dedicated to diagnostic information providers. \n
  * It is permitted only to an app signed by platform level certificates.
  *
  * @param[in] event_name Diagnostics event name
@@ -432,7 +435,7 @@ API int diagnostics_send_event(const char *event_name, bundle *event_data);
 /**
  * @brief Gets a system diagnostics client's ID (event sender).
  * @since_tizen 6.0
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * @a client_id should be released with free().
  *
  * @param[in] ctx Diagnostics context handle
@@ -464,7 +467,7 @@ API int diagnostics_get_client_id(diagnostics_ctx_h ctx, char **client_id);
 /**
  * @brief Gets a copy of system diagnostics client's event name.
  * @since_tizen 6.5
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * @a event_name should be released with free().
  *
  * @param[in] ctx Diagnostics context handle
@@ -496,7 +499,7 @@ API int diagnostics_get_event_name(diagnostics_ctx_h ctx, char **event_name);
 /**
  * @brief Gets a copy of a system diagnostics event's attached data.
  * @since_tizen 6.5
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * @a event_data should be released with bundle_free().
  *
  * @param[in] ctx Diagnostics context handle
@@ -528,7 +531,7 @@ API int diagnostics_get_event_data(diagnostics_ctx_h ctx, bundle **event_data);
 /**
  * @brief Sets the system diagnostics client ID for further calls.
  * @since_tizen 6.5
- * @remarks This function is dedicated to diagnostic information providers. \n
+ * @details This function is dedicated to diagnostic information providers. \n
  * As services do not have any name associated with them, ID must be set explicitly with this function before calling any of the following functions: \n
  * diagnostics_set_data_request_cb() \n
  * diagnostics_send_event() \n
@@ -552,7 +555,7 @@ API int diagnostics_set_client_id(const char *client_id);
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/bugreport.admin
- * @remarks This function is dedicated to diagnostic information subscribers. \n
+ * @details This function is dedicated to diagnostic information subscribers. \n
  * To get bugreport's content, user must subscribe to 'BugreportCreated' diagnostics event, which is sent by crash-service after creating the report.
  *
  * @param[in] pid ID of a process that should be livedumped. When @a pid <= 0, system-wide bugreport is created.
@@ -568,6 +571,7 @@ API int diagnostics_request_bugreport(int pid);
 
 /**
  * @brief Frees the resources of a system diagnostics data handle.
+ * @details This function must be used at the end of the handle's lifetime to avoid a memory leak.
  * @since_tizen 6.0
  *
  * @param[in] data Diagnostics data handle
@@ -581,6 +585,7 @@ API int diagnostics_data_destroy(diagnostics_data_h data);
 
 /**
  * @brief Frees the resources of a system diagnostics context handle.
+ * @details This function must be used at the end of the handle's lifetime, in the notification handler, to avoid a memory leak.
  * @since_tizen 6.0
  *
  * @param[in] ctx Diagnostics context handle