From 419604a4d29a4f705fd308c4d435e94b64576de1 Mon Sep 17 00:00:00 2001
From: apio <blobs.trading@gmail.com>
Date: Mon, 28 Aug 2023 11:10:04 +0200
Subject: [PATCH] libluna: Document Buffer

---
 libluna/include/luna/Buffer.h | 102 ++++++++++++++++++++++++++++++++++
 libluna/src/Buffer.cpp        |   9 +++
 2 files changed, 111 insertions(+)

diff --git a/libluna/include/luna/Buffer.h b/libluna/include/luna/Buffer.h
index 6b378815..cd711c0a 100644
--- a/libluna/include/luna/Buffer.h
+++ b/libluna/include/luna/Buffer.h
@@ -1,7 +1,19 @@
+/**
+ * @file Buffer.h
+ * @author apio (cloudapio.eu)
+ * @brief A managed wrapper around a resizable buffer of arbitrary memory.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Result.h>
 #include <luna/Types.h>
 
+/**
+ * @brief A managed wrapper around a resizable buffer of arbitrary memory.
+ */
 class Buffer
 {
   public:
@@ -11,45 +23,135 @@ class Buffer
     Buffer(Buffer&& other);
     Buffer(const Buffer& other) = delete; // For now.
 
+    /**
+     * @brief Create a Buffer object, allocating a specific amount of memory for it.
+     *
+     * @param size The number of bytes to allocate.
+     * @return Result<Buffer> An error, or the newly created buffer.
+     */
     static Result<Buffer> create_sized(usize size);
 
+    /**
+     * @brief Resize the buffer.
+     *
+     * The existing data is kept, unless the new size is smaller than the old size, in which case only the first
+     * new_size bytes are kept.
+     *
+     * @param new_size The new size of the buffer, in bytes.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> try_resize(usize new_size);
 
+    /**
+     * @brief Expand the buffer and return a pointer to the beginning of this new expanded area.
+     *
+     * @param size The amount of bytes to expand the buffer by.
+     * @return Result<u8*> An error, or a pointer to the new area of the buffer.
+     */
     Result<u8*> slice_at_end(usize size);
 
+    /**
+     * @brief Return a pointer to an area of the buffer, expanding it if necessary.
+     *
+     * @param offset The offset inside the buffer to start at.
+     * @param size The amount of bytes to reserve.
+     * @return Result<u8*> An error, or a pointer to the requested area.
+     */
     Result<u8*> slice(usize offset, usize size);
 
+    /**
+     * @brief Add data to the end of the buffer.
+     *
+     * @param data A pointer to the data to add.
+     * @param size The amount of bytes to add.
+     * @return Result<void> Whether the operation succeeded.
+     */
     Result<void> append_data(const u8* data, usize size);
 
+    /**
+     * @brief Remove data from the beginning of the buffer and return it.
+     *
+     * @param data A pointer to store the removed data in.
+     * @param size The amount of bytes to remove.
+     * @return usize The amount of bytes actually removed (may be less if the buffer was smaller than the requested
+     * size).
+     */
     usize dequeue_data(u8* data, usize size);
 
+    /**
+     * @brief Return a pointer to the data contained in the buffer.
+     *
+     * This pointer may be invalid after the buffer is resized.
+     *
+     * @return u8* The contained data.
+     */
     u8* data()
     {
         return m_data;
     }
 
+    /**
+     * @brief Return a pointer to the data contained in the buffer.
+     *
+     * This pointer may be invalid after the buffer is resized.
+     *
+     * @return const u8* The contained data.
+     */
     const u8* data() const
     {
         return m_data;
     }
 
+    /**
+     * @brief Return a pointer to the data contained in the buffer, moving the data out of the buffer.
+     *
+     * This call will empty the buffer, making it the caller's responsibility to manage the data, including freeing it
+     * when no longer used.
+     *
+     * @return u8* The released data.
+     */
     u8* release_data();
 
+    /**
+     * @brief Return a pointer to the end of the data contained in the buffer.
+     *
+     * This pointer points past the data; as such, dereferencing it directly is undefined behavior.
+     *
+     * @return u8* The end of the data.
+     */
     u8* end()
     {
         return m_data + m_size;
     }
 
+    /**
+     * @brief Return a pointer to the end of the data contained in the buffer.
+     *
+     * This pointer points past the data; as such, dereferencing it directly is undefined behavior.
+     *
+     * @return const u8* The end of the data.
+     */
     const u8* end() const
     {
         return m_data + m_size;
     }
 
+    /**
+     * @brief Return the size of the buffer in bytes.
+     *
+     * @return usize The buffer's size.
+     */
     usize size() const
     {
         return m_size;
     }
 
+    /**
+     * @brief Check whether the buffer is empty.
+     *
+     * @return true The buffer is empty.
+     * @return false The buffer is not empty.
+     */
     bool is_empty() const
     {
         return m_size == 0;
diff --git a/libluna/src/Buffer.cpp b/libluna/src/Buffer.cpp
index 57f53051..b0a0b29b 100644
--- a/libluna/src/Buffer.cpp
+++ b/libluna/src/Buffer.cpp
@@ -1,3 +1,12 @@
+/**
+ * @file Buffer.cpp
+ * @author apio (cloudapio.eu)
+ * @brief A managed wrapper around a resizable buffer of arbitrary memory.
+ *
+ * @copyright Copyright (c) 2023, the Luna authors.
+ *
+ */
+
 #include <luna/Buffer.h>
 #include <luna/CString.h>
 #include <luna/Heap.h>