Add missing comments

2 files changed, 51 insertions, 21 deletions

diff --git a/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp b/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp
index 4ccc6a9..5ff13ca 100644
--- a/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp
+++ b/arch/x86_64/include/arch/memory/heap/linked_list_allocator.hpp
@@ -61,12 +61,10 @@ namespace teachos::arch::memory::heap
      * @param previous_block Free memory block before the block to allocate in our heap memory. Was to small to
      * allocate the required size into.
      * @param current_block Free memory block we want to remove from the free list and return for the allocation.
-     * @param size Size we want to allocate that is exactly the same as the size of the curernt block
      *
-     * @return Previous start address of the memory block we removed, because it has the exact required size.
+     * @return Previous start address of the memory block we removed, because it can now be used for the allocation.
      */
-    auto remove_free_memory_block(memory_block * previous_block, memory_block * current_block,
-                                  std::size_t size) -> void *;
+    auto remove_free_memory_block(memory_block * previous_block, memory_block * current_block) -> void *;
 
     /**
      * @brief Splits the given free memory block into two, where the latter block keeps being free and the first
@@ -78,28 +76,42 @@ namespace teachos::arch::memory::heap
      * future allocations.
      * @param size Size we want to allocate at the start of the free memory block.
      *
-     * @return Previous start address of the memory block we just split.
+     * @return Previous start address of the memory block we just split, because it can now be used for the allocation.
      */
     auto split_free_memory_block(memory_block * previous_block, memory_block * current_block,
                                  std::size_t size) -> void *;
 
     /**
+     * @brief Removes a free memory block from the free list and returns its address so the caller can allocate into it.
+     *
+     * @param previous_block Free memory block before the block to allocate in our heap memory. Was to small to
+     * allocate the required size into.
+     * @param current_block Free memory block we want to remove from the free list and return for the allocation.
+     * @param new_block Replaces the current block with the given new block can be nullptr, meaning the free list will
+     * end here.
+     *
+     * @return Previous start address of the memory block we removed, because it can now be used for the allocation.
+     */
+    auto replace_free_memory_block(memory_block * previous_block, memory_block * current_block,
+                                   memory_block * new_block) -> void *;
+
+    /**
      * @brief Combines multiple free memory blocks into one if they are adjacent.
      *
      * @note The internal algorithm for recombination functions like this:
-     * 1. Check if there is even any memory left, if not the first entry of our linked list should be a nullptr and we
-     * can therefore set the first entry to our newly created entry. This entry is created in the now deallocated memory
-     * area.
-     * 2. If there are more blocks but neither the previous nor the current block are adjacent, we simply create a new
-     * free memory block of the given size and set the previous next to our block and the next of our block to the
-     * current block.
+     * 1. Check if there is even any memory left, if not the first entry of our linked list should be a nullptr and
+     * we can therefore set the first entry to our newly created entry. This entry is created in the now deallocated
+     * memory area.
+     * 2. If there are more blocks but neither the previous nor the current block are adjacent, we simply create a
+     * new free memory block of the given size and set the previous next to our block and the next of our block to
+     * the current block.
      * 3. If the current block is adjacent the start address of the newly created block stays the same, but the size
      * increases by the amount in the current memory block header. After reading it we also clear the header.
-     * 4. If the previous block is adjacent the size of the previous block simply increases to include the given size as
-     * well.
-     * 5. If the previous block is directly in our start address, so they overlap then it has to mean some or all of the
-     * region we are trying to deallocate has been freed before. Which would result in a double free therefore we halt
-     * the execution of the program.
+     * 4. If the previous block is adjacent the size of the previous block simply increases to include the given
+     * size as well.
+     * 5. If the previous block is directly in our start address, so they overlap then it has to mean some or all of
+     * the region we are trying to deallocate has been freed before. Which would result in a double free therefore
+     * we halt the execution of the program.
      *
      * @param previous_block Free memory block before the block to deallocate in our heap memory.
      * @param current_block Free memory block after the block to deallocate in our heap memory.
diff --git a/arch/x86_64/include/arch/shared/mutex.hpp b/arch/x86_64/include/arch/shared/mutex.hpp
index 36a4623..ecd4490 100644
--- a/arch/x86_64/include/arch/shared/mutex.hpp
+++ b/arch/x86_64/include/arch/shared/mutex.hpp
@@ -5,33 +5,51 @@
 
 namespace teachos::arch::shared
 {
+  /**
+   * @brief Custom mutex implementation, that simply wraps an atomic boolean to keep track if the mutex is already in
+   * use by another thread or not.
+   */
   struct mutex
   {
+    /**
+     * @brief Defaulted constructor.
+     */
     mutex() = default;
+
+    /**
+     * @brief Defaulted destructor.
+     */
     ~mutex() = default;
 
+    /**
+     * @brief Deleted copy constructor.
+     */
     mutex(const mutex &) = delete;
+
+    /**
+     * @brief Deleted assignment operator.
+     */
     mutex & operator=(const mutex &) = delete;
 
     /**
-     * @brief Lock the mutex (blocks if not available)
+     * @brief Lock the mutex (blocks for as long as it is not available).
      */
     auto lock() -> void;
 
     /**
-     * @brief Try to lock the mutex (non-blocking)
+     * @brief Try to lock the mutex (non-blocking).
      *
-     * @return true if lock has been acquired and false otherwise
+     * @return True if lock has been acquired and false otherwise.
      */
     auto try_lock() -> bool;
 
     /**
-     * @brief Unlock the mutex
+     * @brief Unlock the mutex.
      */
     auto unlock() -> void;
 
   private:
-    std::atomic<bool> locked{false};
+    std::atomic<bool> locked = {false};  // Atomic boolean to track if mutex is locked or not.
   };
 }  // namespace teachos::arch::shared
 #endif  // TEACHOS_ARCH_X86_64_MUTEX_HPP
\ No newline at end of file