From 08061b8e4b02f6aff3aa70c01bf1ea6569f77973 Mon Sep 17 00:00:00 2001
From: Antoine <angagnie@student.42.fr>
Date: Tue, 3 Sep 2024 23:14:28 +0800
Subject: [PATCH] Document the color header and include it in the reference

---
 book/pages/reference/arg_count.md |  4 ++
 book/pages/reference/color.md     |  4 ++
 book/pages/reference/fold.md      |  4 ++
 book/pages/reference/index.md     |  3 ++
 include/blackmagic/color.h        | 75 ++++++++++++++++++++-----------
 include/blackmagic/log.h          |  4 +-
 6 files changed, 67 insertions(+), 27 deletions(-)
 create mode 100644 book/pages/reference/arg_count.md
 create mode 100644 book/pages/reference/color.md
 create mode 100644 book/pages/reference/fold.md

diff --git a/book/pages/reference/arg_count.md b/book/pages/reference/arg_count.md
new file mode 100644
index 0000000..b0dcb92
--- /dev/null
+++ b/book/pages/reference/arg_count.md
@@ -0,0 +1,4 @@
+# Counting arguments
+
+:::{doxygenfile} arg_count.h
+:::
diff --git a/book/pages/reference/color.md b/book/pages/reference/color.md
new file mode 100644
index 0000000..37fe0b9
--- /dev/null
+++ b/book/pages/reference/color.md
@@ -0,0 +1,4 @@
+# Terminal colors
+
+:::{doxygenfile} color.h
+:::
diff --git a/book/pages/reference/fold.md b/book/pages/reference/fold.md
new file mode 100644
index 0000000..4ee11fe
--- /dev/null
+++ b/book/pages/reference/fold.md
@@ -0,0 +1,4 @@
+# Fold
+
+:::{doxygenfile} fold.h
+:::
diff --git a/book/pages/reference/index.md b/book/pages/reference/index.md
index 488fac9..3af5380 100644
--- a/book/pages/reference/index.md
+++ b/book/pages/reference/index.md
@@ -2,5 +2,8 @@
 
 :::{toctree}
 token
+arg_count
+fold
+color
 log
 :::
diff --git a/include/blackmagic/color.h b/include/blackmagic/color.h
index f7e5da8..7cccb52 100644
--- a/include/blackmagic/color.h
+++ b/include/blackmagic/color.h
@@ -1,36 +1,59 @@
 #pragma once
 
+/**
+ * @file
+ *
+ */
+
 #include "blackmagic/token.h" // STRINGIZE
 #include "blackmagic/fold.h" // FOLD
 
+/** @name Font style */
+///@{
+/**
+ * Reset font style.
+ * A color sequence with only `NORMAL` resets all style, color and background color
+ */
 #define NORMAL     0
-#define BOLD       1
-#define DIM        2
-#define ITALIC     3
-#define UNDERLINED 4
-#define NEGATIVE   6
+#define BOLD       1 /**< . */
+#define DIM        2 /**< . */
+#define ITALIC     3 /**< . */
+#define UNDERLINED 4 /**< . */
+#define NEGATIVE   6 /**< . */
+///@}
 
-#define BLACK      30
-#define RED        31
-#define GREEN      32
-#define YELLOW     33
-#define BLUE       34
-#define PURPLE     35
-#define CYAN       36
-#define LIGHT_GREY 37
-#define DEFAULT    39
-#define WHITE      97
+/** @name Font color */
+///@{
+#define BLACK      30 /**< . */
+#define RED        31 /**< . */
+#define GREEN      32 /**< . */
+#define YELLOW     33 /**< . */
+#define BLUE       34 /**< . */
+#define PURPLE     35 /**< . */
+#define CYAN       36 /**< . */
+#define LIGHT_GREY 37 /**< . */
+#define DEFAULT    39 /**< Reset font color */
+#define WHITE      97 /**< . */
+///@}
 
-#define BG_BLACK      40
-#define BG_RED        41
-#define BG_GREEN      42
-#define BG_YELLOW     43
-#define BG_BLUE       44
-#define BG_PURPLE     45
-#define BG_CYAN       46
-#define BG_LIGHT_GREY 47
-#define BG_DEFAULT    49
-#define BG_WHITE      107
+/** @name Background color */
+///@{
+#define BG_BLACK      40 /**< . */
+#define BG_RED        41 /**< . */
+#define BG_GREEN      42 /**< . */
+#define BG_YELLOW     43 /**< . */
+#define BG_BLUE       44 /**< . */
+#define BG_PURPLE     45 /**< . */
+#define BG_CYAN       46 /**< . */
+#define BG_LIGHT_GREY 47 /**< . */
+#define BG_DEFAULT    49 /**< Reset background color */
+#define BG_WHITE      107 /**< . */
+///@}
 
-#define COLOR_JOIN(A, B) A;B
+/**
+ * Expands to a string literal containig an escape code setting the terminal color.
+ * @since 0.1
+ */
 #define COLOR(...) STRINGIZE(\e[FOLD(COLOR_JOIN __VA_OPT__(,) __VA_ARGS__)m)
+
+#define COLOR_JOIN(A, B) A;B
diff --git a/include/blackmagic/log.h b/include/blackmagic/log.h
index 8342471..dc79b61 100644
--- a/include/blackmagic/log.h
+++ b/include/blackmagic/log.h
@@ -21,6 +21,7 @@
 /**
  * Choose the file to output logs to.
  * What is expected is a `FILE*` like `stdout` or `stderr`.
+ *
  * Defaults to `stderr`
  */
 #	define LOG_FILE stderr
@@ -33,6 +34,7 @@
 /**
  * Choose the compile-time log verbosity level.
  * Logs that are strictly less critical that this level are removed before compilation.
+ *
  * The default value is @ref LOG_LEVEL_TRACE for debug builds and @ref LOG_LEVEL_INFO for release builds that define `NDEBUG`.
  */
 #		define LOG_LEVEL LOG_LEVEL_TRACE
@@ -92,7 +94,7 @@
 #	define log_log(LEVEL, IGNORED, MESSAGE, ...) \
 		fprintf(LOG_FILE, "|" LEVEL "|`" __FILE__ "`|`%s`|" STRINGIZE(__LINE__) "|" MESSAGE "|\n", __func__ __VA_OPT__(, ) __VA_ARGS__)
 #else
-#	define log_log(L, C, M, ...)
+#	define log_log(L, C, M, ...) /* Logs are disabled */
 #endif
 
 #if LOG_LEVEL >= LOG_LEVEL_FATAL