libluna: Document Bitmap

libluna/include/luna/Bitmap.h

@@ -1,58 +1,195 @@
+/**
+ * @file Bitmap.h
+ * @author apio (cloudapio.eu)
+ * @brief An interface to an array of bits.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #pragma once
 #include <luna/Result.h>
 #include <luna/Types.h>
 
+/**
+ * @brief A class providing an interface to an array of bits.
+ */
 class Bitmap
 {
   public:
+    /**
+     * @brief Construct a new empty Bitmap object.
+     *
+     * This object is invalid until initialize() is called on it.
+     */
     Bitmap();
+
+    /**
+     * @brief Construct a new Bitmap object.
+     *
+     * @param location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you must
+     * free it after it is no longer used by the bitmap.
+     * @param size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the memory used.
+     */
     Bitmap(void* location, usize size_in_bytes);
 
-    // Naive initialization functions.
+    /**
+     * @brief Initialize a Bitmap object.
+     *
+     * If the object was previously initialized, you should call move() instead.
+     *
+     * @param location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you must
+     * free it after it is no longer used by the bitmap.
+     * @param size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the memory used.
+     */
     void initialize(void* location, usize size_in_bytes);
+
+    /**
+     * @brief Initialize a previously initialized Bitmap object and return the memory location it was previously using.
+     *
+     * If the object was not previously initialized, you should call initialize() instead.
+     *
+     * @param new_location The memory to use. This memory is not managed by Bitmap; if it is dynamically allocated, you
+     * must free it after it is no longer used by the bitmap.
+     * @param new_location_size_in_bytes The size (in bytes, the number of bits available will be 8 times more) of the
+     * memory used.
+     * @return void* The old memory location previously used by the bitmap.
+     */
     void* move(void* new_location, usize new_location_size_in_bytes);
 
-    // Dynamic memory initialization functions.
-    Result<void> allocate(usize size_in_bytes);
-    Result<void*> resize(usize new_size_in_bytes);
-    Result<void> deallocate();
-
+    /**
+     * @brief Change the value of the bit at a specific index.
+     *
+     * @param index The index of the bit to change.
+     * @param value The value to set.
+     */
     void set(usize index, bool value);
+
+    /**
+     * @brief Read the value of the bit at a specific index.
+     *
+     * @param index The index of the bit to read.
+     * @return bool The value of the specified bit.
+     */
     bool get(usize index) const;
 
-    // size() returns size in bits! If you want the size in bytes, call size_in_bytes().
+    /**
+     * @brief Return the size in bits of the bitmap.
+     *
+     * @return usize The size in bits.
+     */
     usize size() const
     {
         return m_size_in_bytes * 8;
     }
 
+    /**
+     * @brief Return the size in bytes of the bitmap.
+     *
+     * @return usize The size in bytes.
+     */
     usize size_in_bytes() const
     {
         return m_size_in_bytes;
     }
 
+    /**
+     * @brief Return the memory location used by the bitmap.
+     *
+     * @return void* The memory location used. If it is NULL, the bitmap was not initialized.
+     */
     void* location() const
     {
         return (void*)m_location;
     }
 
+    /**
+     * @brief Check whether the bitmap has been initialized.
+     *
+     * @return true The bitmap was initialized by a constructor or initialize().
+     * @return false The bitmap was not initialized and you should not call other methods on it until initialize() is
+     * called.
+     */
     bool initialized() const
     {
         return m_location;
     }
 
+    /**
+     * @brief Find the first bit with a specific value.
+     *
+     * @param value The value to look for.
+     * @param begin If different from 0, the bit index to start looking at.
+     * @return Option<usize> If a matching bit was found, the index of said bit, otherwise an empty Option.
+     */
     Option<usize> find(bool value, usize begin = 0) const;
 
+    /**
+     * @brief Find the first bit with a specific value and toggle it.
+     *
+     * @param value The value to look for.
+     * @param begin If different from 0, the bit index to start looking at.
+     * @return Option<usize> If a matching bit was found, the index of said bit, otherwise an empty Option.
+     */
     Option<usize> find_and_toggle(bool value, usize begin = 0);
 
+    /**
+     * @brief Find the first region of bits all with a specific value.
+     *
+     * @param value The value to look for.
+     * @param count The number of consecutive bits that should all match the value.
+     * @param begin If different from 0, the bit index to start looking at.
+     * @return Option<usize> If a matching region was found, the index of the first bit in said region, otherwise an
+     * empty Option.
+     */
     Option<usize> find_region(bool value, usize count, usize begin = 0) const;
 
+    /**
+     * @brief Find the first region of bits all with a specific value, and toggle them all.
+     *
+     * @param value The value to look for.
+     * @param count The number of consecutive bits that should all match the value.
+     * @param begin If different from 0, the bit index to start looking at.
+     * @return Option<usize> If a matching region was found, the index of the first bit in said region, otherwise an
+     * empty Option.
+     */
     Option<usize> find_and_toggle_region(bool value, usize count, usize begin = 0);
 
+    /**
+     * @brief Check whether a region of bits all match a value.
+     *
+     * @param start The bit index of the first bit in the region.
+     * @param bits The number of bits in the region.
+     * @param value The value to check against.
+     * @return bool Whether the region matches.
+     */
     bool match_region(usize start, usize bits, bool value);
+
+    /**
+     * @brief Check whether a region of bits all match a value, returning an error if the region is outside of the
+     * Bitmap's bounds (instead of crashing).
+     *
+     * @param start The bit index of the first bit in the region.
+     * @param bits The number of bits in the region.
+     * @param value The value to check against.
+     * @return Result<bool> An error if the region is out of bounds, or whether the region matches.
+     */
     Result<bool> try_match_region(usize start, usize bits, bool value);
 
+    /**
+     * @brief Set the entire bitmap to a value.
+     *
+     * @param value The value to use.
+     */
     void clear(bool value);
+
+    /**
+     * @brief Set a region of bits to a value.
+     *
+     * @param start The bit index of the first bit in the region.
+     * @param bits The number of bits in the region.
+     * @param value The value to set.
+     */
     void clear_region(usize start, usize bits, bool value);
 
   private:

libluna/src/Bitmap.cpp

@@ -1,3 +1,12 @@
+/**
+ * @file Bitmap.cpp
+ * @author apio (cloudapio.eu)
+ * @brief An interface to an array of bits.
+ *
+ * @copyright Copyright (c) 2022-2023, the Luna authors.
+ *
+ */
+
 #include <luna/Bitmap.h>
 #include <luna/CString.h>
 #include <luna/Check.h>
@@ -17,24 +26,6 @@ void Bitmap::initialize(void* location, usize size_in_bytes)
     m_size_in_bytes = size_in_bytes;
 }
 
-Result<void> Bitmap::allocate(usize size_in_bytes)
-{
-    initialize(TRY(malloc_impl(size_in_bytes)), size_in_bytes);
-    return {};
-}
-
-Result<void*> Bitmap::resize(usize new_size_in_bytes)
-{
-    m_location = (u8*)TRY(realloc_impl(m_location, new_size_in_bytes));
-    m_size_in_bytes = new_size_in_bytes;
-    return (void*)m_location;
-}
-
-Result<void> Bitmap::deallocate()
-{
-    return free_impl(m_location);
-}
-
 void* Bitmap::move(void* new_location, usize new_location_size_in_bytes)
 {
     if (new_location_size_in_bytes > m_size_in_bytes) memcpy(new_location, m_location, m_size_in_bytes);