From: Michal Bloch Date: Wed, 25 Sep 2024 18:33:51 +0000 (+0200) Subject: Add 50+ char long @details sections to docs X-Git-Tag: accepted/tizen/unified/20241001.004112^0 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fheads%2Faccepted%2Ftizen_unified;p=platform%2Fcore%2Fapi%2Fdiagnostics.git 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 af211b8..e09329d 100644 --- 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 diff --git a/include/diagnostics.h b/include/diagnostics.h index 42ec85d..4070ff2 100644 --- 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