libluna: Document CircularQueue, CPath and CRC32

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/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/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,