From 558dc8a681dc0182b3b7719e28e43ee781f2adb8 Mon Sep 17 00:00:00 2001 From: Michal Bloch Date: Thu, 26 Sep 2024 21:12:57 +0200 Subject: [PATCH] Add @details docs. Change-Id: I2ed323bb036267ce3ecfdde646dff63502354000 --- doc/dlogutil_doc.h | 2 ++ include/dlog-redirect-stdout.h | 2 +- include/dlog.h | 4 ++++ include/dlogutil.h | 48 +++++++++++++++++++++++++++++++++++------- 4 files changed, 47 insertions(+), 9 deletions(-) diff --git a/doc/dlogutil_doc.h b/doc/dlogutil_doc.h index 024c421..bfdf991 100644 --- a/doc/dlogutil_doc.h +++ b/doc/dlogutil_doc.h @@ -20,6 +20,8 @@ /** * @defgroup CAPI_SYSTEM_DLOGUTIL libdlogutil * @brief The libdlogutil API provides functions for receiving logs programatically + * @details libdlogutil lets you retrieve logs much like the dlogutil CLI tool. + * In fact, dlogutil is just a trivial client of libdlogutil. See the overview section for more. * @ingroup CAPI_SYSTEM_FRAMEWORK * @section CAPI_SYSTEM_DLOGUTIL_HEADER Required Header * \#include diff --git a/include/dlog-redirect-stdout.h b/include/dlog-redirect-stdout.h index 44ed0ef..0cb6c9c 100644 --- a/include/dlog-redirect-stdout.h +++ b/include/dlog-redirect-stdout.h @@ -50,7 +50,7 @@ int dlog_connect_fd(int buffer, int fileno, const char *tag, int prio); /** * @brief Check whether a file descriptor has been opened via DLog - * @remarks Use for low-level code that does bulk operations on FDs (for example, close them all) + * @details Use for low-level code that does bulk operations on FDs (for example, close them all) * but still wants to be able to use DLog interfaces afterwards. * @bug DLog devices opened manually (i.e. not via library) are still returned as positives. * On the other hand, /dev/null is always returned as a negative even if opened via DLog. diff --git a/include/dlog.h b/include/dlog.h index 16e49aa..ef95e1a 100644 --- a/include/dlog.h +++ b/include/dlog.h @@ -25,6 +25,7 @@ * @file dlog.h * @version 0.4 * @brief This file is the header file of the interface of Dlog. + * @details Interfaces for DLog, the default system-wide logger for Tizen. */ @@ -64,6 +65,7 @@ extern "C" { /** * @brief Enumeration for Dlog Errors, returned by API calls. + * @details Some of DLog API calls can return these to denote what happened. * @since_tizen 2.3 */ typedef enum { @@ -86,6 +88,8 @@ typedef enum { /** * @brief Enumeration for log priority values in ascending priority order. + * @details Priority level controls how important a message is. This is both + * a way to a developer to gauge it and for tools to filter for it. * @since_tizen 2.3 */ typedef enum { diff --git a/include/dlogutil.h b/include/dlogutil.h index a210853..7f95553 100644 --- a/include/dlogutil.h +++ b/include/dlogutil.h @@ -39,6 +39,8 @@ extern "C" { /** * @brief Enumeration for timestamp-based log sorting orderings + * @details Log messages get up to 4 different timestamps which don't necessarily produce the same ordering. + * This enum lets you specify which ordering you want in given context. * @since_tizen 6.0 * @remarks For information on the timestamp documentation, refer to @ref CAPI_SYSTEM_DLOGUTIL_OVERVIEW. */ @@ -53,12 +55,15 @@ typedef enum { /** * @brief A struct containing the metadata and contents for a single dlog entry. + * @details An individual log, received after all filters were applied. + * @bug Currently missing a dlogutil_entry_destroy() function. Use regular libc free(). * @since_tizen 6.0 */ typedef struct dlogutil_entry dlogutil_entry_s; /** * @brief Retrieves the TID (thread identificator) of the log sender. + * @details Retrieves the TID who sent a log, useful for debugging multithreaded programs. * @since_tizen 6.0 * @remarks If LOG_ID_KMSG is used as the buffer, this function will always return * TIZEN_ERROR_NO_DATA. This is because the KMSG buffer contains no TID information. @@ -73,6 +78,7 @@ int dlogutil_entry_get_tid(const dlogutil_entry_s *entry, pid_t *tid); /** * @brief Retrieves the PID (process identificator) of the log sender. + * @details Retrieves the PID who sent a log, useful for debugging in a multi-program environment. * @since_tizen 6.0 * @remarks If LOG_ID_KMSG is used as the buffer, this function will always return * TIZEN_ERROR_NO_DATA. This is because the KMSG buffer contains no PID information. @@ -87,6 +93,9 @@ int dlogutil_entry_get_pid(const dlogutil_entry_s *entry, pid_t *pid); /** * @brief Retrieves the tag (arbitrary label) of the log entry. + * @details Gets the log's tag, which has two main purposes. + * One is to identify multiple instances of the same program. + * The other is to identify subcomponents of a program, e.g. libraries. * @since_tizen 6.0 * @remarks The tag is owned by the entry so do not free nor modify it. * In some rare cases the entry may be malformed and the message may turn out to be unavailable. @@ -102,6 +111,7 @@ int dlogutil_entry_get_tag(const dlogutil_entry_s *entry, const char **tag); /** * @brief Retrieves the message (without any metadata) of the log entry. + * @details Gets the raw message itself, which is the essence of a log. * @since_tizen 6.0 * @remarks The message is owned by the entry so do not free nor modify it. * In some rare cases the entry may be malformed and the message may turn out to be unavailable. @@ -117,6 +127,7 @@ int dlogutil_entry_get_message(const dlogutil_entry_s *entry, const char **msg); /** * @brief Retrieves the timestamp of given type from the log entry. + * @details Gets the timestamp of a log, which lets you know when it was sent. * @since_tizen 6.0 * @remarks The information about timestamp availability can be retrieved using the dlogutil_buffer_check_ts_type_available() function. * For information on the timespec struct, refer to the clock_gettime(2) manpage. @@ -134,6 +145,8 @@ int dlogutil_entry_get_timestamp(const dlogutil_entry_s *entry, dlogutil_sorting /** * @brief Retrieves the priority level metadata of the log entry. + * @details Checks how important the log was. Note that you only receive logs + * that pass any priority filters you set, so you don't need to worry about chaff. * @since_tizen 6.0 * @param[in] entry Log entry * @param[out] prio Log priority @@ -146,12 +159,14 @@ int dlogutil_entry_get_priority(const dlogutil_entry_s *entry, log_priority *pri /** * @brief A struct containing libdlogutil initialisation configuration. + * @details This is the handle to a one-time setup you have to do before sending a log retrieval request. * @since_tizen 6.0 */ typedef struct dlogutil_config dlogutil_config_s; /** * @brief Creates a new #dlogutil_config_s struct to be filled with configuration. + * @details Creates a config to be filled in, this is the first function you should call. * @since_tizen 6.0 * @remarks Needs to be freed using dlogutil_config_destroy(). * @return A handle to the new struct, or NULL if out of memory @@ -161,6 +176,7 @@ dlogutil_config_s *dlogutil_config_create(void); /** * @brief Destroys the #dlogutil_config_s struct and cleans up its memory. + * @details Frees resources of a config. Call it after you've connected and received a dlogutil state. * @since_tizen 6.0 * @param[in] config A handle to the settings struct * @see dlogutil_config_create() @@ -169,7 +185,7 @@ void dlogutil_config_destroy(dlogutil_config_s *config); /** * @brief Enables retrieving only those logs that are logged by the thread with the given TID. - * @remarks Useful for dumping the logs of a specific thread in a multithreaded process. + * @details Filters by TID. Useful for dumping the logs of a specific thread in a multithreaded process. * @since_tizen 6.0 * @param[in] config A handle to the settings struct * @param[in] tid The TID value @@ -182,7 +198,7 @@ int dlogutil_config_filter_tid(dlogutil_config_s *config, pid_t tid); /** * @brief Enables retrieving only those logs that are logged by the process with the given PID. - * @remarks Useful for dumping the logs of a specific process. + * @details Filters by PID. Useful for dumping the logs of a specific process. * @since_tizen 6.0 * @param[in] config A handle to the settings struct. * @param[in] pid The PID value. @@ -195,6 +211,7 @@ int dlogutil_config_filter_pid(dlogutil_config_s *config, pid_t pid); /** * @brief Enables retrieving only those logs that match a given filter. + * @details Filters by tag and priority. Useful for dumping logs of a specific program or subcomponent, or of sufficient importance. * @since_tizen 6.0 * @param[in] config A handle to the settings struct. * @param[in] query The filter query. For syntax, see dlogutil's --help or @ref CAPI_SYSTEM_DLOG_UTIL documentation. @@ -208,7 +225,7 @@ int dlogutil_config_filter_filterspec(dlogutil_config_s *config, const char *que /** * @brief Disables log sorting for given log retrieval request. - * @remarks Logs are still received in some order that is usually largely sorted, + * @details Logs are still received in some order that is usually largely sorted, * but if sorting is disabled logutil-side there may be cases where a log * with a later timestamp is in front of a log with an earlier one. * The use case here is performance, since the failure case above is rare. @@ -225,7 +242,7 @@ int dlogutil_config_sorting_disable(dlogutil_config_s *config); /** * @brief Enables log sorting for given log retrieval request. * @since_tizen 6.0 - * @remarks This is the default and generally makes sure that logs are in order, + * @details Makes sure logs are sorted. This is the default * but has a modest performance cost. * @param[in] config A handle to the settings struct * @return An error code @@ -256,7 +273,7 @@ int dlogutil_config_sorting_enable_with_size(dlogutil_config_s *config, unsigned /** * @brief Chooses a timestamp type by which returned logs are sorted by * @since_tizen 6.0 - * @remarks If the chosen timestamp is missing in the logs, currently they will not be sorted at all. + * @details If the chosen timestamp is missing in the logs, currently they will not be sorted at all. * This should, however, still become a reasonable order, since logs are usually stored * sorted by one of timestamps. * If only some logs are missing the chosen timestamp, ordering of the logs is undefined. @@ -271,6 +288,7 @@ int dlogutil_config_order_set(dlogutil_config_s *config, dlogutil_sorting_order_ /** * @brief Adds a buffer whence logs will be taken to a request. + * @details Specifies which buffer to retrieve logs from. Usually this will be main or apps. * @since_tizen 6.0 * @param[in] config A handle to the settings struct * @param[in] buf The buffer ID to add to the handled set @@ -283,6 +301,7 @@ int dlogutil_config_buffer_add(dlogutil_config_s *config, log_id_t buf); /** * @brief Enables the full dump mode which prints every stored log + * @details Pass this constant when you want to dump everything and not just N most recent logs. * @since_tizen 6.0 * @see dlogutil_config_mode_set_dump() */ @@ -290,12 +309,15 @@ int dlogutil_config_buffer_add(dlogutil_config_s *config, log_id_t buf); /** * @brief A struct containing the state of a log handling request + * @details Represents a connection to dlog backend. You can't change config + * anymore at this point, but can start retrieving logs. * @since_tizen 6.0 */ typedef struct dlogutil_state dlogutil_state_s; /** * @brief Destroys the #dlogutil_state_s struct and frees its memory + * @details Use after you're done retrieving logs and are cleaning up. * @since_tizen 6.0 * @param[in] state A handle to the state struct * @see dlogutil_config_connect() @@ -304,6 +326,7 @@ void dlogutil_state_destroy(dlogutil_state_s *state); /** * @brief Set log retrieval mode to retrieving all the logs since the start of the system without an end. + * @details Essentially a dump, followed by monitoring. See those modes. * @since_tizen 6.0 * @remarks This is similar to dlogutil in a default mode. * @param[in,out] config The configuration struct @@ -318,6 +341,7 @@ int dlogutil_config_mode_set_continuous(dlogutil_config_s *config); /** * @brief Set log retrieval mode to retrieving all the logs since the call without an end. + * @details Will only retrieve new logs. Any logs present before the connection are ignored. Good for live debugging. * @since_tizen 6.0 * @remarks This is similar to dlogutil -m. * @param[in,out] config The configuration struct @@ -333,6 +357,7 @@ int dlogutil_config_mode_set_monitor(dlogutil_config_s *config); /** * @brief Set log retrieval mode to dumping all the logs since the start of the system until the call * (possibly a specified amount of the most recent of them instead). + * @details Will only retrieve existing logs. Any logs incoming after the connection are ignored. Good for avoiding floods. * @since_tizen 6.0 * @remarks This is similar to dlogutil -d. After dumping all the logs, dlogutil_get_log() will signal this by returning TIZEN_ERROR_NO_DATA. * @param[in,out] config The configuration struct @@ -349,6 +374,7 @@ int dlogutil_config_mode_set_dump(dlogutil_config_s *config, unsigned int entry_ /** * @brief Set log retrieval mode to dumping compressed historical logs + * @details Similar to the dump mode, but works on a named compressed buffer. * @since_tizen 7.0 * @remarks This is similar to `cat /var/log/dlog/xyz`. After dumping all the logs, dlogutil_get_log() will signal this by returning TIZEN_ERROR_NO_DATA. * @param[in,out] config The configuration struct @@ -366,6 +392,7 @@ int dlogutil_config_mode_set_compressed_memory_dump(dlogutil_config_s *config, c /** * @brief Finalizes the config into a state struct by connecting to buffers + * @details Gives you a state, letting you start getting logs. You can get rid of the config at this point. * @since_tizen 6.0 * @remarks An application having platform privilege level can read platform log data * by declaring %http://tizen.org/privilege/log, which has been added since 6.5. @@ -386,6 +413,7 @@ int dlogutil_config_connect(dlogutil_config_s *config, dlogutil_state_s **state_ /** * @brief Retrieves a single log according to a dump request + * @details Gets a log from the backend. See the API for dlogutil entry. * @since_tizen 6.0 * @remarks If the calling process doesn't have CAP_SYSLOG and is not in the log group, you will only get * some of the logs. Also, you must set the mode (dlogutil_config_mode_set_*). @@ -408,6 +436,7 @@ int dlogutil_get_log(dlogutil_state_s *state, int timeout, dlogutil_entry_s **en /** * @brief Irreversibly clears a log buffer from any logs inside + * @details Tells the backend to get rid of any stored logs. Good for chaff management. * @since_tizen 6.0 * @remarks You can't use one of the log-getting modes (dlogutil_config_mode_set_*). * @param[in] state A handle to the state struct @@ -425,6 +454,7 @@ int dlogutil_buffer_clear(dlogutil_state_s *state, log_id_t buffer); /** * @brief Gets the human-readable, constant name of a buffer + * @details Gets the name of a buffer according to dlog. Mostly for convenience. * @since_tizen 6.0 * @remarks The returned string will have the static lifetime. * @param[in] buffer A buffer to be inspected @@ -438,6 +468,7 @@ int dlogutil_buffer_get_name(log_id_t buffer, const char **name); /** * @brief Gets the data storage capacity of a log buffer in bytes + * @details Returns how many bytes of logs can fit in given buffer on the backend. * @since_tizen 6.0 * @remarks Either CAP_SYSLOG or being in the log group is required. * Also, you can't use one of the log-getting modes (dlogutil_config_mode_set_*). @@ -461,6 +492,7 @@ int dlogutil_buffer_get_capacity(dlogutil_state_s *state, log_id_t buffer, unsig /** * @brief Gets the storage data usage of a log buffer, in bytes + * @details Returns how many bytes of logs are currently stored in given buffer on the backend. * @since_tizen 6.0 * @remarks Either CAP_SYSLOG or being in the log group is required. * Also, you can't use one of the log-getting modes (dlogutil_config_mode_set_*). @@ -485,7 +517,7 @@ int dlogutil_buffer_get_usage(dlogutil_state_s *state, log_id_t buffer, unsigned /** * @brief Gets the default sorting timestamp type of a buffer. * @since_tizen 6.0 - * @remarks This is the timestamp type that will be used for sorting by default. + * @details This is the timestamp type that will be used for sorting by default. * We assume that it is always available and the input is sorted by it. * See @ref CAPI_SYSTEM_DLOGUTIL_OVERVIEW for more details. * @bug This is currently evaluated using the config file, which can change at runtime. In particular, @@ -506,7 +538,7 @@ int dlogutil_buffer_get_default_ts_type(log_id_t buffer, dlogutil_sorting_order_ /** * @brief Checks if a buffer contains timestamps of a given type. * @since_tizen 6.0 - * @remarks If false is returned, the timestamp may still be available in some of the logs. + * @details If false is returned, the timestamp may still be available in some of the logs. * However, if true is returned, the timestamp will always be available. * You can check the timestamp availability per log using the dlogutil_entry_get_timestamp() function. * @bug This is currently evaluated using the config file, which can change at runtime. In particular, @@ -528,7 +560,7 @@ int dlogutil_buffer_check_ts_type_available(log_id_t buffer, dlogutil_sorting_or /** * @brief Gets the buffer aliasing (same storage) information * @since_tizen 6.0 - * @remarks Sometimes, multiple buffers will be backed by a single log storage (for example, by the same + * @details Sometimes, multiple buffers will be backed by a single log storage (for example, by the same * kernel device). In such cases, the storage will only be opened once. This function allows you * to see whether this is the case. * @bug This is currently evaluated using the config file, which can change at runtime. In particular, -- 2.7.4