Extend @brief docs to 50+ chars

Change-Id: I06655f8324b4af195e40c515d01b14e9b9731bb9
Signed-off-by: Michal Bloch <m.bloch@samsung.com>

diff --git a/include/diagnostics.h b/include/diagnostics.h
index 682a3786dbe0fb3f358410a62a35fb3fce00f8b1..42ec85daaaf7f33c81a98330027306bdb7314f8e 100644 (file)
--- a/include/diagnostics.h
+++ b/include/diagnostics.h
@@ -33,19 +33,19 @@ extern "C" {
  */
 
 /**
- * @brief Diagnostics context.
+ * @brief An opaque handle to a system diagnostics context object.
  * @since_tizen 6.0
  */
 typedef void* diagnostics_ctx_h;
 
 /**
- * @brief Diagnostics data.
+ * @brief An opaque handle to a system diagnostics data object.
  * @since_tizen 6.0
  */
 typedef void* diagnostics_data_h;
 
 /**
- * @brief Enumeration for error codes of Diagnostics.
+ * @brief Enumeration for error codes returned by the diagnostics API.
  * @since_tizen 6.0
  */
 typedef enum {
@@ -143,7 +143,7 @@ API int diagnostics_unset_notification_cb(void);
 
 /**
  * @platform
- * @brief Subscribes to an event sent by diagnostics client.
+ * @brief Subscribes to an event sent by a diagnostics client.
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
@@ -167,7 +167,7 @@ API int diagnostics_subscribe_event(const char *event_name, const char *client_i
 
 /**
  * @platform
- * @brief Sets the callback for diagnostics data request.
+ * @brief Sets the callback for a system diagnostics data request.
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
@@ -219,7 +219,7 @@ API int diagnostics_set_data_request_cb(diagnostics_request_cb callback, void *u
 
 /**
  * @platform
- * @brief Unsets the callback for diagnostics data request.
+ * @brief Unsets the callback for a diagnostics data request.
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
@@ -236,7 +236,7 @@ API int diagnostics_unset_data_request_cb(void);
 
 /**
  * @platform
- * @brief Requests diagnostics client to dump data.
+ * @brief Requests a system diagnostics client to dump given data.
  * @since_tizen 6.0
  * @privlevel platform
  * @privilege
@@ -332,7 +332,7 @@ API int diagnostics_request_client_data(const char *client_id, const char **para
 API int diagnostics_get_data(diagnostics_ctx_h ctx, const char **params, int params_size, diagnostics_data_h *data);
 
 /**
- * @brief Gets a file descriptor for diagnostics data.
+ * @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
  * instead of using our diagnostics_data_read() and diagnostics_data_write() functions. \n
@@ -348,7 +348,7 @@ API int diagnostics_get_data(diagnostics_ctx_h ctx, const char **params, int par
 API int diagnostics_data_get_fd(diagnostics_data_h data, int *fd);
 
 /**
- * @brief Reads diagnostics data.
+ * @brief Perform a single iteration of reading diagnostics data.
  * @since_tizen 6.0
  * @remarks 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.
@@ -371,7 +371,7 @@ API int diagnostics_data_get_fd(diagnostics_data_h data, int *fd);
 API int diagnostics_data_read(diagnostics_data_h data, void *buf, size_t count, int timeout_ms, size_t *bytes_read);
 
 /**
- * @brief Writes diagnostics data.
+ * @brief Perform a single iteration of writing diagnostics data.
  * @since_tizen 6.5
  * @remarks 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.
@@ -393,7 +393,7 @@ API int diagnostics_data_write(diagnostics_data_h data, const void *buf, size_t
 
 /**
  * @platform
- * @brief Sends diagnostics event.
+ * @brief Sends a system diagnostics event to a previously specified client.
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege
@@ -430,7 +430,7 @@ API int diagnostics_data_write(diagnostics_data_h data, const void *buf, size_t
 API int diagnostics_send_event(const char *event_name, bundle *event_data);
 
 /**
- * @brief Gets diagnostics client ID (event sender).
+ * @brief Gets a system diagnostics client's ID (event sender).
  * @since_tizen 6.0
  * @remarks This function is dedicated to diagnostic information subscribers. \n
  * @a client_id should be released with free().
@@ -462,7 +462,7 @@ API int diagnostics_send_event(const char *event_name, bundle *event_data);
 API int diagnostics_get_client_id(diagnostics_ctx_h ctx, char **client_id);
 
 /**
- * @brief Gets diagnostics event name.
+ * @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
  * @a event_name should be released with free().
@@ -494,7 +494,7 @@ API int diagnostics_get_client_id(diagnostics_ctx_h ctx, char **client_id);
 API int diagnostics_get_event_name(diagnostics_ctx_h ctx, char **event_name);
 
 /**
- * @brief Gets diagnostics event data.
+ * @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
  * @a event_data should be released with bundle_free().
@@ -526,7 +526,7 @@ API int diagnostics_get_event_name(diagnostics_ctx_h ctx, char **event_name);
 API int diagnostics_get_event_data(diagnostics_ctx_h ctx, bundle **event_data);
 
 /**
- * @brief Sets the diagnostics client ID.
+ * @brief Sets the system diagnostics client ID for further calls.
  * @since_tizen 6.5
  * @remarks 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
@@ -548,7 +548,7 @@ API int diagnostics_set_client_id(const char *client_id);
 
 /**
  * @platform
- * @brief Requests bugreport creation.
+ * @brief Requests the creation of a bugreport, either systemwide or livedump a specific process.
  * @since_tizen 6.5
  * @privlevel platform
  * @privilege %http://tizen.org/privilege/bugreport.admin
@@ -567,7 +567,7 @@ API int diagnostics_set_client_id(const char *client_id);
 API int diagnostics_request_bugreport(int pid);
 
 /**
- * @brief Frees diagnostics data.
+ * @brief Frees the resources of a system diagnostics data handle.
  * @since_tizen 6.0
  *
  * @param[in] data Diagnostics data handle
@@ -580,7 +580,7 @@ API int diagnostics_request_bugreport(int pid);
 API int diagnostics_data_destroy(diagnostics_data_h data);
 
 /**
- * @brief Frees diagnostics context.
+ * @brief Frees the resources of a system diagnostics context handle.
  * @since_tizen 6.0
  *
  * @param[in] ctx Diagnostics context handle