libluna: Document Format

libluna/include/luna/CPath.h

@@ -1,7 +1,29 @@
+/**
+ * @file CPath.h
+ * @author apio (cloudapio.eu)
+ * @brief Basic operations on paths using C-style strings.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 
 extern "C"
 {
-    char* basename(char*);
-    char* dirname(char*);
+    /**
+     * @brief Get the base name of a path.
+     *
+     * @param path The path to use. This will be modified.
+     * @return char* A pointer to the base name (usually points inside path).
+     */
+    char* basename(char* path);
+
+    /**
+     * @brief Get the parent directory of a path.
+     *
+     * @param path The path to use. This will be modified.
+     * @return char* A pointer to the directory (usually points inside path).
+     */
+    char* dirname(char* path);
 }

libluna/include/luna/CRC32.h

@@ -1,11 +1,34 @@
+/**
+ * @file CRC32.h
+ * @author apio (cloudapio.eu)
+ * @brief CRC32 checksum calculation.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Types.h>
 
+/**
+ * @brief A class to calculate a CRC32 checksum.
+ */
 class CRC32
 {
   public:
+    /**
+     * @brief Add data to the checksum.
+     *
+     * @param data The data to add.
+     * @param size The amount of bytes to add.
+     */
     void append(const u8* data, usize size);
 
+    /**
+     * @brief Calculate the final checksum.
+     *
+     * @return u32 The calculated checksum.
+     */
     u32 digest();
 
   private:

libluna/include/luna/CString.h

@@ -1,3 +1,12 @@
+/**
+ * @file CString.h
+ * @author apio (cloudapio.eu)
+ * @brief Implementations of C-string and memory manipulation functions.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Types.h>
 

libluna/include/luna/CType.h

@@ -1,3 +1,13 @@
+/**
+ * @file CType.h
+ * @author apio (cloudapio.eu)
+ * @brief Implementations of C-like character classification functions, prefixed with an underscore to avoid conflicting
+ * with libc.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 
 inline constexpr int _isascii(int c)

libluna/include/luna/CircularQueue.h

@@ -1,9 +1,24 @@
+/**
+ * @file CircularQueue.h
+ * @author apio (cloudapio.eu)
+ * @brief Lock-free FIFO data structures.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Atomic.h>
 #include <luna/Heap.h>
 #include <luna/Result.h>
 #include <luna/Types.h>
 
+/**
+ * @brief An atomic lock-free circular FIFO queue.
+ *
+ * @tparam T The type of data to store in this queue.
+ * @tparam Size The amount of elements to make space for.
+ */
 template <typename T, usize Size> class CircularQueue
 {
     enum
@@ -16,11 +31,24 @@ template <typename T, usize Size> class CircularQueue
     {
     }
 
+    /**
+     * @brief Return whether the queue is empty.
+     *
+     * @return true The queue is empty.
+     * @return false The queue is not empty.
+     */
     bool is_empty()
     {
         return m_tail.load() == m_head.load();
     }
 
+    /**
+     * @brief Push a value onto the queue.
+     *
+     * @param value The value to push.
+     * @return true The operation succeded.
+     * @return false The queue was full or someone else was trying to push a value at the same time.
+     */
     bool try_push(const T& value)
     {
         usize current_tail = m_tail.load(MemoryOrder::Relaxed);
@@ -39,6 +67,13 @@ template <typename T, usize Size> class CircularQueue
         return true;
     }
 
+    /**
+     * @brief Pop a value from the queue.
+     *
+     * @param value The variable to store the value into.
+     * @return true The operation succeded.
+     * @return false The queue was empty or someone else was trying to pop a value at the same time.
+     */
     bool try_pop(T& value)
     {
         usize current_head = m_head.load(MemoryOrder::Relaxed);
@@ -63,6 +98,13 @@ template <typename T, usize Size> class CircularQueue
     Atomic<usize> m_tail = 0;
 };
 
+/**
+ * @brief An atomic lock-free circular FIFO queue.
+ *
+ * In this variant the size is set at runtime.
+ *
+ * @tparam T The type of data to store in this queue.
+ */
 template <typename T> class DynamicCircularQueue
 {
 
@@ -76,18 +118,41 @@ template <typename T> class DynamicCircularQueue
         if (m_data) free_impl(m_data);
     }
 
+    /**
+     * @brief Return whether the queue is empty.
+     *
+     * @return true The queue is empty.
+     * @return false The queue is not empty.
+     */
     bool is_empty()
     {
         return m_tail.load() == m_head.load();
     }
 
+    /**
+     * @brief Set the size of the queue and allocate memory for it.
+     *
+     * This should not be used to grow the queue, as all existing data is lost. In most cases, this function will only
+     * be called once to set the initial size of the queue and that's it.
+     *
+     * @param size The amount of elements to make space for.
+     * @return Result<void> Whether the operation succeded.
+     */
     Result<void> set_size(usize size)
     {
+        if (m_data) free_impl(m_data);
         m_data = (T*)TRY(calloc_impl(size + 1, sizeof(T), false));
         m_capacity = size + 1;
         return {};
     }
 
+    /**
+     * @brief Push a value onto the queue.
+     *
+     * @param value The value to push.
+     * @return true The operation succeded.
+     * @return false The queue was full or someone else was trying to push a value at the same time.
+     */
     bool try_push(const T& value)
     {
         check(m_capacity);
@@ -107,6 +172,13 @@ template <typename T> class DynamicCircularQueue
         return true;
     }
 
+    /**
+     * @brief Pop a value from the queue.
+     *
+     * @param value The variable to store the value into.
+     * @return true The operation succeded.
+     * @return false The queue was empty or someone else was trying to pop a value at the same time.
+     */
     bool try_pop(T& value)
     {
         check(m_capacity);

libluna/include/luna/DebugLog.h

@@ -1,7 +1,33 @@
+/**
+ * @file DebugLog.h
+ * @author apio (cloudapio.eu)
+ * @brief Debug logging for platform-agnostic functions.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Attributes.h>
 #include <stdarg.h>
 
+/**
+ * @brief The actual debug log implementation. This must be provided by the platform or user.
+ *
+ * In the kernel, the implementation is located in src/Log.cpp.
+ * For POSIX systems, libluna provides an implementation in src/ImplPOSIX.cpp.
+ *
+ * The printed message must be followed by an implicit newline.
+ *
+ * @param format The format string (in the style of printf).
+ * @param ap The variadic argument list.
+ */
 extern void debug_log_impl(const char* format, va_list ap);
 
+/**
+ * @brief Log a formatted message.
+ *
+ * @param format The format string (in the style of printf).
+ * @param ... The format arguments.
+ */
 void dbgln(const char* format, ...) _format(1, 2);

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);

libluna/src/CPath.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file CPath.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Basic operations on paths using C-style strings.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/CPath.h>
 #include <luna/CString.h>
 

libluna/src/CRC32.cpp

@@ -1,5 +1,13 @@
+/**
+ * @file CRC32.cpp
+ * @author apio (cloudapio.eu)
+ * @brief CRC32 checksum calculation.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/CRC32.h>
-#include <luna/DebugLog.h>
 
 static const u32 crc_table[] = {
     0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832,

libluna/src/CString.cpp

@@ -1,6 +1,15 @@
-#include <luna/Alloc.h>
+/**
+ * @file CString.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Implementations of C-string and memory manipulation functions.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #include <luna/CString.h>
 #include <luna/CType.h>
+#include <luna/Heap.h>
 
 extern "C"
 {

libluna/src/CppABI.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file CppABI.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Implementation of some C++ ABI internal functions, mainly __cxa_atexit.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 typedef void* (*cxa_atexit_func_t)(void*);
 
 struct cxa_atexit_entry

libluna/src/DebugLog.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file DebugLog.cpp
+ * @author apio (cloudapio.eu)
+ * @brief Debug logging for platform-agnostic functions.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #include <luna/DebugLog.h>
 
 void dbgln(const char* format, ...)

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;