doc FEATURE high level documentation including transition manual
diff --git a/src/log.h b/src/log.h
index 27e6fcd..1766fbe 100644
--- a/src/log.h
+++ b/src/log.h
@@ -32,11 +32,50 @@
typedef uint8_t ly_bool;
/**
+ * @page howtoLogger Information Logging
+ *
+ * The libyang logger is supposed to process all the messages (and some other accompanied information) generated by the performed
+ * functions. According to the logger settings, the information can be printed, stored or further processed by a callback
+ * functions.
+ *
+ * The logger is tightly connected with [errors handling](@ref howtoErrors), because when an error appears, the logger (according
+ * to [logger options](@ref logopts)) generates error records available via libyang context.
+ *
+ * There are 4 verbosity levels defined as ::LY_LOG_LEVEL. The level can be changed by the ::ly_log_level() function.
+ * By default, the verbosity level is set to #LY_LLERR value, so only the errors are processed.
+ *
+ * By default, all libyang messages are printed to `stderr`. However, the callers are able to set their own logging callback
+ * function (::ly_log_clb). In that case, instead of printing messages, libyang passes error level, message and path (if any) to
+ * the caller's callback function set via ::ly_set_log_clb(). In case of error level, the error information is still
+ * automatically stored and available via the [error handling functions](@ref howtoErrors).
+ *
+ * With [logging options](@ref logopts) set via ::ly_log_options(), the caller can modify what is done with all the messages.
+ * Default flags are ::LY_LOLOG and ::LY_LOSTORE_LAST so that messages are logged and the last one is stored. If you set the flag
+ * ::LY_LOSTORE, all the messages will be stored. Be careful because unless you regularly clean them, the error list in context
+ * will grow indefinitely.
+ *
+ * As a separate group, there are @ref dbggroup to select group of debugging messages to print. The options can be set via
+ * ::ly_log_dbg_groups() function, but note that the options take effect only in case the libyang is compiled in
+ * [Debug build mode](@ref building).
+ *
+ * \note API for this group of functions is described in the [logger module](@ref log).
+ *
+ * Functions List
+ * --------------
+ * - ::ly_log_level()
+ * - ::ly_log_dbg_groups()
+ * - ::ly_log_options()
+ * - ::ly_set_log_clb()
+ * - ::ly_get_log_clb()
+ *
+ */
+
+/**
* @defgroup log Logger
* @{
*
* Publicly visible functions and values of the libyang logger. For more
- * information, see \ref howtologger.
+ * information, see \ref howtoLogger.
*/
/**
@@ -49,7 +88,7 @@
LY_LLWRN = 1, /**< Print error and warning messages. */
LY_LLVRB = 2, /**< Besides errors and warnings, print some other verbose messages. */
LY_LLDBG = 3 /**< Print all messages including some development debug messages (be careful,
- without subsequently calling ly_verb_dbg() no debug messages will be printed!). */
+ without subsequently calling ::ly_log_dbg_groups() no debug messages will be printed!). */
} LY_LOG_LEVEL;
/**
@@ -60,11 +99,13 @@
LY_LOG_LEVEL ly_log_level(LY_LOG_LEVEL level);
/**
- * @defgroup logopts Logging options
* @ingroup logger
+ * @defgroup logopts Logging options
*
* Logging option bits of libyang.
*
+ * Can be set via ::ly_log_options().
+ *
* @{
*/
#define LY_LOLOG 0x01 /**< Log messages normally, using callback if set. If not set, messages will
@@ -79,7 +120,7 @@
*/
/**
- * @brief Set additional logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
+ * @brief Set logger options. Default is #LY_LOLOG | #LY_LOSTORE_LAST.
*
* @param[in] opts Bitfield of @ref logopts.
* @return Previous logger options.
@@ -89,10 +130,12 @@
#ifndef NDEBUG
/**
- * @defgroup dbggroup Debug message groups
* @ingroup log
+ * @defgroup dbggroup Debug messages groups
*
- * Selected displayed debug message groups.
+ * Categories of the debug messages.
+ *
+ * Allows to show only the selected group(s) of the debug messages.
*
* @{
*/
@@ -120,7 +163,7 @@
*
* !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
* at the time of calling this callback. It will be set right after, so to retrieve it
- * it must be checked afterwards with ly_errapptag().
+ * it must be checked afterwards with ::ly_errapptag().
*
* @param[in] level Log level of the message.
* @param[in] msg Message.
@@ -149,7 +192,39 @@
/** @} log */
/**
+ * @page howtoErrors Errors Handling
+ *
+ * The most of the API functions directly returns error code in the form of ::LY_ERR value. In addition, if the ::LY_EVALID error
+ * arises, additional [validation error code](@ref ::LY_VECODE) is provided to categorize validation failures into several groups.
+ *
+ * All the errors arisen in connection with manipulation with the [context](@ref howtoContext), [YANG modules](@ref howtoSchema)
+ * or [YANG data](@ref howtoData), are recorded into the context and can be examined for the more detailed information. These
+ * records are stored as ::ly_err_item structures and they are not only context-specific, but also thread-specific.
+ *
+ * Storing error information is tightly connected with
+ * [logging](@ref howtoLogger). So the @ref logopts control if and which errors are stored in the context. By default, only the
+ * last error is recorded, so a new error replaces the previous one. This can be changed with ::LY_LOSTORE option set via
+ * ::ly_log_options(). Then, the errors are stored as a list preserving the previous error records. The stored records can be
+ * accessed using ::ly_err_last() or ::ly_err_first() functions. The ::ly_err_clean() is used to remove error records from the
+ * context.
+ *
+ * To print a specific error information via libyang logger, there is ::ly_err_print().
+ *
+ * To simplify access to the last error record in the context, there is a set of functions returning important error information.
+ * - ::ly_errapptag()
+ * - ::ly_errcode()
+ * - ::ly_vecode()
+ * - ::ly_errmsg()
+ * - ::ly_errpath()
+ *
+ * \note API for this group of functions is described in the [error information module](@ref errors).
+ */
+
+/**
* @defgroup errors Error information
+ *
+ * Structures and functions to allow error information processing.
+ *
* @{
*/
@@ -178,10 +253,10 @@
} LY_ERR;
/**
+ * @ingroup logger
* @typedef LY_VECODE
* @brief libyang's codes of validation error. Whenever ly_errno is set to LY_EVALID, the ly_vecode is also set
* to the appropriate LY_VECODE value.
- * @ingroup logger
*/
typedef enum {
LYVE_SUCCESS = 0, /**< no error */
@@ -235,7 +310,7 @@
* a specific error message, it will be used instead the default one.
*
* Sometimes, the error message is extended with path of the element where the problem is.
- * The path is available via ly_errpath().
+ * The path is available via ::ly_errpath().
*
* @param[in] ctx Relative context.
* @return Text of the last error message, empty string if there is no error.
@@ -245,7 +320,7 @@
/**
* @brief Get the last (thread, context-specific) path of the element where was an error.
*
- * The path always corresponds to the error message available via ly_errmsg(), so
+ * The path always corresponds to the error message available via ::ly_errmsg(), so
* whenever a subsequent error message is printed, the path is erased or rewritten.
* The path reflects the type of the processed tree - data path for data tree functions
* and schema path in case of schema tree functions. In case of processing YIN schema
@@ -261,7 +336,7 @@
* @brief Get the last (thread, context-specific) error-app-tag if there was a specific one defined
* in the module for the last error.
*
- * The app-tag always corresponds to the error message available via ly_errmsg(), so
+ * The app-tag always corresponds to the error message available via ::ly_errmsg(), so
* whenever a subsequent error message is printed, the app-tag is erased or rewritten.
*
* @param[in] ctx Relative context.