Extend docs to 50 chars

As requested by corporate rules.

Change-Id: I2ed323bb036267ce3ecfdde646dff63502353cd2

diff --git a/doc/dlog_conf.h b/doc/dlog_conf.h
index 3464d60..5d4df9d 100644 (file)
--- a/doc/dlog_conf.h
+++ b/doc/dlog_conf.h
@@ -1,7 +1,7 @@
 /**
  @defgroup CLI_DLOGCONF dlog config
  @ingroup DLOG_COMMAND_LINE_UTILITIES
- @brief DLog configuration
+ @brief DLog configuration files provide a way to customize DLog behaviour
  @details Configuration for various DLog components
 
 Important config entries:

diff --git a/include/dlog-redirect-stdout.h b/include/dlog-redirect-stdout.h
index 2d518a3..44ed0ef 100644 (file)
--- a/include/dlog-redirect-stdout.h
+++ b/include/dlog-redirect-stdout.h
@@ -26,7 +26,37 @@
 extern "C" {
 #endif
 
+/**
+ * @brief Open an unstructured connection to a DLog logging sink
+ * @details Opens a connection to which you can stream data.
+ *          DLog will automatically convert it to individual logs appropriately.
+ * @remarks Useful for redirecting stdout to DLog
+ * @param[in] buffer Target DLog buffer
+ * @param[in] fileno File descriptor to use for the connection
+ * @param[in] tag DLog tag for the resulting logs
+ * @param[in] prio Priority for the resulting logs
+ * @return An error code (negative errno)
+ * @retval 0 Success
+ * @retval -EINVAL Buffer invalid or does not allow connections
+ * @retval -EPERM Buffer disabled via dlog config
+ * @retval -ENOKEY Buffer not configured via dlog config
+ * @retval -ENOTSUP Unsupported DLog backend
+ * @retval -EINVAL Tag empty or unspecified
+ * @retval -EINVAL Priority invalid
+ * @retval -EINVAL Fileno invalid
+ * @retval Other Any errno returnable by dup2, open, or ioctl syscalls
+ */
 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)
+ *          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.
+ * @param[in] fd File descriptor number
+ * @return bool Whether the descriptor refers to a DLog file
+ */
 _Bool dlog_is_log_fd(int fd);
 
 #ifdef __cplusplus

diff --git a/include/dlog.h b/include/dlog.h
index 06498ec..16e49aa 100644 (file)
--- a/include/dlog.h
+++ b/include/dlog.h
@@ -24,7 +24,7 @@
 /**
  * @file dlog.h
  * @version    0.4
- * @brief This file is the header file of interface of Dlog.
+ * @brief This file is the header file of the interface of Dlog.
  */
 
 
@@ -63,7 +63,7 @@ extern "C" {
 
 
 /**
- * @brief Enumeration for Dlog Error.
+ * @brief Enumeration for Dlog Errors, returned by API calls.
  * @since_tizen 2.3
  */
 typedef enum {
@@ -114,8 +114,8 @@ typedef enum {
 
 
 /**
- * @brief Sends log with priority and tag.
- * @details for application.
+ * @brief Sends a log message with given priority and tag, using printf formatting
+ * @details Produces a log and sends it to be stored on the DLog backend for later retrieval via dlogutil CLI tool.
  * @since_tizen 2.3
  * @param[in] prio priority level of type #log_priority
  * @param[in] tag tag - a null-terminated string
@@ -145,8 +145,8 @@ int dlog_print(log_priority prio, const char *tag, const char *fmt, ...)  __attr
 
 
 /**
- * @brief Sends log with priority, tag, and va_list.
- * @details for application.
+ * @brief Sends a log message with given priority and tag label, using variadic args
+ * @details Produces a log and sends it to be stored on the DLog backend for later retrieval via dlogutil CLI tool.
  * @since_tizen 2.3
  * @param[in] prio priority level of type #log_priority
  * @param[in] tag tag - a null-terminated string

diff --git a/include/dlogutil.h b/include/dlogutil.h
index 2587710..a210853 100644 (file)
--- a/include/dlogutil.h
+++ b/include/dlogutil.h
@@ -38,7 +38,7 @@ extern "C" {
  */
 
 /**
- * @brief Enumeration for sorting orders.
+ * @brief Enumeration for timestamp-based log sorting orderings
  * @since_tizen 6.0
  * @remarks For information on the timestamp documentation, refer to @ref CAPI_SYSTEM_DLOGUTIL_OVERVIEW.
  */
@@ -52,13 +52,13 @@ typedef enum {
 } dlogutil_sorting_order_e;
 
 /**
- * @brief A struct containing a single log entry.
+ * @brief A struct containing the metadata and contents for a single dlog entry.
  * @since_tizen 6.0
  */
 typedef struct dlogutil_entry dlogutil_entry_s;
 
 /**
- * @brief Retrieves the TID of the log sender.
+ * @brief Retrieves the TID (thread identificator) of the log sender.
  * @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.
@@ -72,7 +72,7 @@ typedef struct dlogutil_entry dlogutil_entry_s;
 int dlogutil_entry_get_tid(const dlogutil_entry_s *entry, pid_t *tid);
 
 /**
- * @brief Retrieves the PID of the log sender.
+ * @brief Retrieves the PID (process identificator) of the log sender.
  * @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.
@@ -86,7 +86,7 @@ int dlogutil_entry_get_tid(const dlogutil_entry_s *entry, pid_t *tid);
 int dlogutil_entry_get_pid(const dlogutil_entry_s *entry, pid_t *pid);
 
 /**
- * @brief Retrieves the tag of the log entry.
+ * @brief Retrieves the tag (arbitrary label) of the log entry.
  * @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.
@@ -101,7 +101,7 @@ int dlogutil_entry_get_pid(const dlogutil_entry_s *entry, pid_t *pid);
 int dlogutil_entry_get_tag(const dlogutil_entry_s *entry, const char **tag);
 
 /**
- * @brief Retrieves the message of the log entry.
+ * @brief Retrieves the message (without any metadata) of the log entry.
  * @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.
@@ -116,7 +116,7 @@ int dlogutil_entry_get_tag(const dlogutil_entry_s *entry, const char **tag);
 int dlogutil_entry_get_message(const dlogutil_entry_s *entry, const char **msg);
 
 /**
- * @brief Retrieves the timestamp of the log entry.
+ * @brief Retrieves the timestamp of given type from the log entry.
  * @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.
@@ -133,7 +133,7 @@ int dlogutil_entry_get_message(const dlogutil_entry_s *entry, const char **msg);
 int dlogutil_entry_get_timestamp(const dlogutil_entry_s *entry, dlogutil_sorting_order_e order, struct timespec *ts);
 
 /**
- * @brief Retrieves the priority of the log entry.
+ * @brief Retrieves the priority level metadata of the log entry.
  * @since_tizen 6.0
  * @param[in] entry Log entry
  * @param[out] prio Log priority
@@ -145,22 +145,22 @@ int dlogutil_entry_get_timestamp(const dlogutil_entry_s *entry, dlogutil_sorting
 int dlogutil_entry_get_priority(const dlogutil_entry_s *entry, log_priority *prio);
 
 /**
- * @brief A struct containing libdlogutil configuration.
+ * @brief A struct containing libdlogutil initialisation configuration.
  * @since_tizen 6.0
  */
 typedef struct dlogutil_config dlogutil_config_s;
 
 /**
- * @brief Creates a new #dlogutil_config_s struct.
+ * @brief Creates a new #dlogutil_config_s struct to be filled with configuration.
  * @since_tizen 6.0
- * @remarks Needs to be freed using dlogutil_config_destroy()
+ * @remarks Needs to be freed using dlogutil_config_destroy().
  * @return A handle to the new struct, or NULL if out of memory
  * @see dlogutil_config_destroy()
  */
 dlogutil_config_s *dlogutil_config_create(void);
 
 /**
- * @brief Destroys the #dlogutil_config_s struct.
+ * @brief Destroys the #dlogutil_config_s struct and cleans up its memory.
  * @since_tizen 6.0
  * @param[in] config A handle to the settings struct
  * @see dlogutil_config_create()
@@ -169,6 +169,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.
  * @since_tizen 6.0
  * @param[in] config A handle to the settings struct
  * @param[in] tid The TID value
@@ -181,6 +182,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.
  * @since_tizen 6.0
  * @param[in] config A handle to the settings struct.
  * @param[in] pid The PID value.
@@ -205,7 +207,11 @@ int dlogutil_config_filter_pid(dlogutil_config_s *config, pid_t pid);
 int dlogutil_config_filter_filterspec(dlogutil_config_s *config, const char *query);
 
 /**
- * @brief Disables log sorting.
+ * @brief Disables log sorting for given log retrieval request.
+ * @remarks 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.
  * @since_tizen 6.0
  * @param[in] config A handle to the settings struct
  * @return An error code
@@ -217,9 +223,10 @@ int dlogutil_config_filter_filterspec(dlogutil_config_s *config, const char *que
 int dlogutil_config_sorting_disable(dlogutil_config_s *config);
 
 /**
- * @brief Enables sorting.
+ * @brief Enables log sorting for given log retrieval request.
  * @since_tizen 6.0
- * @remarks This is the default.
+ * @remarks This is the default and generally makes sure that logs are in order,
+ *          but has a modest performance cost.
  * @param[in] config A handle to the settings struct
  * @return An error code
  * @retval TIZEN_ERROR_NONE Success
@@ -247,7 +254,7 @@ int dlogutil_config_sorting_enable(dlogutil_config_s *config);
 int dlogutil_config_sorting_enable_with_size(dlogutil_config_s *config, unsigned int entry_count);
 
 /**
- * @brief Chooses a timestamp type to sort by.
+ * @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.
  *       This should, however, still become a reasonable order, since logs are usually stored
@@ -263,7 +270,7 @@ int dlogutil_config_sorting_enable_with_size(dlogutil_config_s *config, unsigned
 int dlogutil_config_order_set(dlogutil_config_s *config, dlogutil_sorting_order_e sort_by);
 
 /**
- * @brief Adds a buffer to be handled
+ * @brief Adds a buffer whence logs will be taken to a request.
  * @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
@@ -275,20 +282,20 @@ int dlogutil_config_order_set(dlogutil_config_s *config, dlogutil_sorting_order_
 int dlogutil_config_buffer_add(dlogutil_config_s *config, log_id_t buf);
 
 /**
- * @brief Enables full dump mode.
+ * @brief Enables the full dump mode which prints every stored log
  * @since_tizen 6.0
  * @see dlogutil_config_mode_set_dump()
  */
 #define DLOGUTIL_MAX_DUMP_SIZE UINT_MAX
 
 /**
- * @brief A struct containing log getting state.
+ * @brief A struct containing the state of a log handling request
  * @since_tizen 6.0
  */
 typedef struct dlogutil_state dlogutil_state_s;
 
 /**
- * @brief Destroys the #dlogutil_state_s struct.
+ * @brief Destroys the #dlogutil_state_s struct and frees its memory
  * @since_tizen 6.0
  * @param[in] state A handle to the state struct
  * @see dlogutil_config_connect()
@@ -378,7 +385,7 @@ int dlogutil_config_mode_set_compressed_memory_dump(dlogutil_config_s *config, c
 int dlogutil_config_connect(dlogutil_config_s *config, dlogutil_state_s **state_out);
 
 /**
- * @brief Gets a single log.
+ * @brief Retrieves a single log according to a dump request
  * @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_*).
@@ -400,7 +407,7 @@ int dlogutil_config_connect(dlogutil_config_s *config, dlogutil_state_s **state_
 int dlogutil_get_log(dlogutil_state_s *state, int timeout, dlogutil_entry_s **entry_out);
 
 /**
- * @brief Clears a log buffer.
+ * @brief Irreversibly clears a log buffer from any logs inside
  * @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
@@ -417,7 +424,7 @@ int dlogutil_get_log(dlogutil_state_s *state, int timeout, dlogutil_entry_s **en
 int dlogutil_buffer_clear(dlogutil_state_s *state, log_id_t buffer);
 
 /**
- * @brief Gets the name of a buffer.
+ * @brief Gets the human-readable, constant name of a buffer
  * @since_tizen 6.0
  * @remarks The returned string will have the static lifetime.
  * @param[in] buffer A buffer to be inspected
@@ -430,7 +437,7 @@ int dlogutil_buffer_clear(dlogutil_state_s *state, log_id_t buffer);
 int dlogutil_buffer_get_name(log_id_t buffer, const char **name);
 
 /**
- * @brief Gets the capacity of a buffer.
+ * @brief Gets the data storage capacity of a log buffer in bytes
  * @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_*).
@@ -453,7 +460,7 @@ int dlogutil_buffer_get_name(log_id_t buffer, const char **name);
 int dlogutil_buffer_get_capacity(dlogutil_state_s *state, log_id_t buffer, unsigned int *capacity);
 
 /**
- * @brief Gets the usage of a buffer.
+ * @brief Gets the storage data usage of a log buffer, in bytes
  * @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_*).
@@ -476,7 +483,7 @@ int dlogutil_buffer_get_capacity(dlogutil_state_s *state, log_id_t buffer, unsig
 int dlogutil_buffer_get_usage(dlogutil_state_s *state, log_id_t buffer, unsigned int *usage);
 
 /**
- * @brief Gets the default timestamp type of a buffer.
+ * @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.
  *          We assume that it is always available and the input is sorted by it.
@@ -519,7 +526,7 @@ int dlogutil_buffer_get_default_ts_type(log_id_t buffer, dlogutil_sorting_order_
 int dlogutil_buffer_check_ts_type_available(log_id_t buffer, dlogutil_sorting_order_e type, bool *available);
 
 /**
- * @brief Gets the buffer aliasing information
+ * @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
  *          kernel device). In such cases, the storage will only be opened once. This function allows you