Mercurial > molko
diff libmlk-core/mlk/core/trace.h @ 541:970cad994a95
core: doxygenize trace
author | David Demelier <markand@malikania.fr> |
---|---|
date | Sun, 05 Mar 2023 13:02:07 +0100 |
parents | 6e8f6640e05b |
children |
line wrap: on
line diff
--- a/libmlk-core/mlk/core/trace.h Sun Mar 05 12:50:11 2023 +0100 +++ b/libmlk-core/mlk/core/trace.h Sun Mar 05 13:02:07 2023 +0100 @@ -19,21 +19,65 @@ #ifndef MLK_CORE_TRACE_H #define MLK_CORE_TRACE_H +/** + * \file mlk/core/trace.h + * \brief Non-fatal message logs + * + * This module provides a simple way to log messages from the API or user code, + * mostly when non-fatal errors happened. + * + * The default implementation uses printf with a timestamp in the form hh:mm::s + * to the standard output, it can be disabled using your own + * ::mlk_trace_handler or setting it to NULL. + * + * Example of lines generated by default: + * + * ``` + * 10:20:30: hello world + * 20:50:00: goodbye world + * ``` + */ + #include <stdarg.h> -#define TRACE_LINE_MAX (1024) +/** + * Maximum trace line + */ +#define MLK_TRACE_LINE_MAX (128) -extern void (*mlk_trace_handler)(const char *); +/** + * Default trace handler implementation + * + * Can be set to NULL to disable logging. + * + * \param line the line to print + */ +extern void (*mlk_trace_handler)(const char *line); #if defined(__cplusplus) extern "C" { #endif +/** + * Write a trace log using a [printf] format style. + * + * [printf]: https://en.cppreference.com/w/c/io/fprintf + * + * \pre fmt != NULL + * \param fmt the printf format string + */ void -mlk_tracef(const char *, ...); +mlk_tracef(const char *fmt, ...); +/** + * Similar to ::mlk_tracef but using a `va_list` instead. + * + * \pre fmt != NULL + * \param fmt the printf format string + * \param ap the variadic handle + */ void -mlk_traceva(const char *, va_list); +mlk_traceva(const char *fmt, va_list ap); #if defined(__cplusplus) }