From 55c362eecf94f3da7c0e0535289373557e590f91 Mon Sep 17 00:00:00 2001
From: apio <blobs.trading@gmail.com>
Date: Sat, 26 Aug 2023 12:59:22 +0200
Subject: [PATCH] libluna: Document Format

---
 libluna/include/luna/Format.h | 61 +++++++++++++++++++++++++++++++----
 libluna/src/Format.cpp        | 13 ++++++--
 2 files changed, 66 insertions(+), 8 deletions(-)

diff --git a/libluna/include/luna/Format.h b/libluna/include/luna/Format.h
index 19c4dfa0..5c5a9b65 100644
--- a/libluna/include/luna/Format.h
+++ b/libluna/include/luna/Format.h
@@ -1,16 +1,65 @@
+/**
+ * @file Format.h
+ * @author apio (cloudapio.eu)
+ * @brief C-style string formatting.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Attributes.h>
 #include <luna/Result.h>
 #include <stdarg.h>
 
-typedef Result<void> (*callback_t)(char, void*);
+/**
+ * @brief The callback type for cstyle_format.
+ *
+ * The first parameter is the resulting character, and the second one is the arbitrary argument passed to cstyle_format.
+ * Functions of this callback type can return errors, which will be propagated by cstyle_format.
+ */
+typedef Result<void> (*FormatCallback)(char, void*);
 
-// Format output according to a format string and a list of variadic arguments. callback is called with arg for every
-// character in the resulting string.
-Result<usize> cstyle_format(const char* format, callback_t callback, void* arg, va_list ap);
+/**
+ * @brief Create a formatted string.
+ *
+ * Since this function uses a callback, it is very flexible; it can format output to a buffer, file, or whatever else is
+ * needed by the caller.
+ *
+ * This function lacks floating-point support, and wide character support, but otherwise, it has almost all C printf
+ * features: width, precision, alignment, size modifiers, and many more...
+ *
+ * This function is used to implemented all printf-related functions in Luna's libc and is the most tested component in
+ * libluna (see TestFormat.cpp, which tests it through String::format).
+ *
+ * @param format The C-style format string.
+ * @param callback The function to be called for every character in the resulting string.
+ * @param arg An arbitrary argument to pass to the callback function.
+ * @param ap The variadic argument list.
+ * @return Result<usize> An error, or the number of characters in the resulting string.
+ */
+Result<usize> cstyle_format(const char* format, FormatCallback callback, void* arg, va_list ap);
 
-// Convenience function which outputs into a fixed-size buffer (not unlike vsnprintf)
+/**
+ * @brief Format a string into a fixed-size buffer.
+ *
+ * @param buf The buffer to store the resulting string into.
+ * @param max The maximum number of bytes to store in the buffer.
+ * @param format The format string.
+ * @param ap The variadic argument list.
+ * @return usize The number of characters in the formatted string. If it is more than or equal to max, the string was
+ * truncated.
+ */
 usize vstring_format(char* buf, usize max, const char* format, va_list ap);
 
-// Convenience function which outputs into a fixed-size buffer (not unlike snprintf)
+/**
+ * @brief Format a string into a fixed-size buffer.
+ *
+ * @param buf The buffer to store the resulting string into.
+ * @param max The maximum number of bytes to store in the buffer.
+ * @param format The format string.
+ * @param ... The format arguments.
+ * @return usize The number of characters in the formatted string. If it is more than or equal to max, the string was
+ * truncated.
+ */
 usize string_format(char* buf, usize max, const char* format, ...) _format(3, 4);
diff --git a/libluna/src/Format.cpp b/libluna/src/Format.cpp
index 3fed3ca0..af927698 100644
--- a/libluna/src/Format.cpp
+++ b/libluna/src/Format.cpp
@@ -1,3 +1,12 @@
+/**
+ * @file Format.cpp
+ * @author apio (cloudapio.eu)
+ * @brief C-style string formatting.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #include <luna/CType.h>
 #include <luna/Format.h>
 #include <luna/NumberParsing.h>
@@ -22,7 +31,7 @@ typedef int flags_t;
 struct format_state
 {
     usize count;
-    callback_t callback;
+    FormatCallback callback;
     void* arg;
 };
 
@@ -385,7 +394,7 @@ static Result<void> va_output_integer(char specifier, conv_state& vstate, format
     }
 }
 
-Result<usize> cstyle_format(const char* format, callback_t callback, void* arg, va_list ap)
+Result<usize> cstyle_format(const char* format, FormatCallback callback, void* arg, va_list ap)
 {
     format_state state;
     state.callback = callback;