Add @details docs.

Change-Id: I2ed323bb036267ce3ecfdde646dff63502354000

diff --git a/doc/dlogutil_doc.h b/doc/dlogutil_doc.h
index 024c421..bfdf991 100644 (file)
--- 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 <dlogutil.h>

diff --git a/include/dlog-redirect-stdout.h b/include/dlog-redirect-stdout.h
index 44ed0ef..0cb6c9c 100644 (file)
--- 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 (file)
--- 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 (file)
--- 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,