# HG changeset patch
# User David Demelier <markand@malikania.fr>
# Date 1678017727 -3600
# Node ID 970cad994a953d4d89b2d6aa99d95c868b4645eb
# Parent  876eee0eb0ad132d6c1101b6ef0b4e0998d2531e
core: doxygenize trace

diff -r 876eee0eb0ad -r 970cad994a95 libmlk-core/mlk/core/trace.c
--- a/libmlk-core/mlk/core/trace.c	Sun Mar 05 12:50:11 2023 +0100
+++ b/libmlk-core/mlk/core/trace.c	Sun Mar 05 13:02:07 2023 +0100
@@ -18,6 +18,7 @@
 
 #include <assert.h>
 #include <stdio.h>
+#include <time.h>
 
 #include "trace.h"
 
@@ -51,11 +52,23 @@
 {
 	assert(fmt);
 
-	char buf[TRACE_LINE_MAX];
+	time_t timestamp;
+	struct tm *calendar;
+	size_t nw;
+	char buf[MLK_TRACE_LINE_MAX + 16];
 
 	if (!mlk_trace_handler)
 		return;
 
-	vsnprintf(buf, sizeof (buf), fmt, ap);
+	/*
+	 * Append default timestamp so that a line looks like this:
+	 *
+	 * 10:10:59: hello world
+	 */
+	timestamp = time(NULL);
+	calendar = localtime(&timestamp);
+	nw = strftime(buf, sizeof (buf), "%T: ", calendar);
+
+	vsnprintf(buf + nw, sizeof (buf) - nw, fmt, ap);
 	mlk_trace_handler(buf);
 }
diff -r 876eee0eb0ad -r 970cad994a95 libmlk-core/mlk/core/trace.h
--- 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)
 }
diff -r 876eee0eb0ad -r 970cad994a95 libmlk-example/mlk/example/trace-hud.c
--- a/libmlk-example/mlk/example/trace-hud.c	Sun Mar 05 12:50:11 2023 +0100
+++ b/libmlk-example/mlk/example/trace-hud.c	Sun Mar 05 13:02:07 2023 +0100
@@ -32,7 +32,7 @@
 #define THEME(t)        ((t) ? (t) : &mlk_theme)
 
 static struct {
-	char lines[LINES_MAX + 1][TRACE_LINE_MAX];
+	char lines[LINES_MAX + 1][MLK_TRACE_LINE_MAX];
 	unsigned int elapsed;
 } data;