docs: improve documentation

2 files changed, 55 insertions, 37 deletions

diff --git a/kapi/include/kapi/memory/frame.hpp b/kapi/include/kapi/memory/frame.hpp
index 10e4172..c8bcb92 100644
--- a/kapi/include/kapi/memory/frame.hpp
+++ b/kapi/include/kapi/memory/frame.hpp
@@ -11,58 +11,57 @@
 namespace teachos::memory
 {
 
+  //! A handle to a frame of physical memory.
   struct frame
   {
+    //! The platform-dependent size of a single frame of memory.
     constexpr auto static size = PLATFORM_FRAME_SIZE;
 
-    constexpr frame() = default;
+    //! Construct a handle referencing the first frame of physical memory.
+    constexpr frame() noexcept = default;
 
-    explicit constexpr frame(std::size_t number)
+    //! Construct a handle referencing the frame of memory with the given frame number.
+    explicit constexpr frame(std::size_t number) noexcept
         : m_number{number}
     {}
 
-    /**
-     * @brief Returns the physical frame the given address is contained in.
-     *
-     * @param address Physical address we want to get the corresponding physical frame for.
-     * @return Frame the given address is contained in.
-     */
+    //! Construct a new frame handle for the frame containing the given address.
+    //!
+    //! @param address A physical address contained by the desired frame.
+    //! @return A handle to a frame containing the given address.
     constexpr auto static containing(physical_address address) noexcept -> frame
     {
       return frame{address.raw() / size};
     }
 
-    /**
-     * @brief Get the start address of this physical frame.
-     *
-     * @return Start address of the physical frame.
-     */
+    //! Get the start address of the frame referenced by this handle.
+    //!
+    //! @return The address of the first byte contained by the frame referenced by this handle.
     [[nodiscard]] constexpr auto start_address() const noexcept -> physical_address
     {
       return physical_address{m_number * size};
     }
 
+    //! Get the number of the frame referenced by this handle.
+    //!
+    //! @return The zero-based number of the frame referenced by this handle.
     [[nodiscard]] constexpr auto number() const noexcept -> std::size_t
     {
       return m_number;
     }
 
-    /**
-     * @brief Get the nth next frame.
-     *
-     * @param offset
-     * @return A new frame n frames after this one.
-     */
+    //! Get a handle n frames after the one referenced by this handle.
+    //!
+    //! @param n The positive offset to this frame.
+    //! @return A handle referencing the frame n frames after the one referenced by this handle.
     constexpr auto operator+(std::size_t n) const noexcept -> frame
     {
       return frame{m_number + n};
     }
 
-    /**
-     * @brief Increment this frame to refer to the next one, returning a copy.
-     *
-     * @return Copy of the incremented underlying frame number.
-     */
+    //! Let this handle reference the next frame after the currently reference one.
+    //!
+    //! @return A handle referencing the same frame as this handle did before the operation.
     constexpr auto operator++(int) noexcept -> frame
     {
       auto copy = *this;
@@ -70,28 +69,27 @@ namespace teachos::memory
       return copy;
     }
 
-    /**
-     * @brief Increment this frame to refer to the next one, returning a this frame.
-     *
-     * @return Reference to the incremented underlying frame number.
-     */
+    //! Let this handle reference the next frame after the currently reference one.
+    //!
+    //! @return A reference to this handle.
     constexpr auto operator++() noexcept -> frame &
     {
       ++m_number;
       return *this;
     }
 
-    /**
-     * @brief Check if this frame refers to the same frame as @p other.
-     */
+    //! Check if this frame handle reference the same frame as another one.
+    //!
+    //! @param other Another frame handle.
     constexpr auto operator==(frame const & other) const noexcept -> bool = default;
 
-    /**
-     * @brief Lexicographically compare this frame to @p other.
-     */
+    //! Compare the number of the frame referenced by this handle to the one reference by another one.
+    //!
+    //! @param other Another frame handle.
     constexpr auto operator<=>(frame const & other) const noexcept -> std::strong_ordering = default;
 
   private:
+    //! The number of the currently referenced frame.
     std::size_t m_number{};
   };
 
diff --git a/kapi/include/kapi/memory/frame_allocator.hpp b/kapi/include/kapi/memory/frame_allocator.hpp
index 6206860..fb6bc0d 100644
--- a/kapi/include/kapi/memory/frame_allocator.hpp
+++ b/kapi/include/kapi/memory/frame_allocator.hpp
@@ -10,12 +10,32 @@
 namespace teachos::memory
 {
 
-  // NOLINTNEXTLINE(cppcoreguidelines-special-member-functions)
+  //! The interface of all frame allocators.
+  //!
+  //! A frame allocator is responsible for the allocation, and deallocation, of frames of physical memory. Frames
+  //! obtained from an allocator shall only be deallocated, or released, via the same allocator. When a frame allocated
+  //! from one allocator is release via a different one (instance or type), the behavior is undefined.
   struct frame_allocator
   {
+    frame_allocator(frame_allocator const &) = delete;
+    frame_allocator(frame_allocator &&) = delete;
+    auto operator=(frame_allocator const &) -> frame_allocator & = delete;
+    auto operator=(frame_allocator &&) -> frame_allocator & = delete;
+
     virtual ~frame_allocator() = default;
-    virtual auto allocate() -> std::optional<frame> = 0;
+
+    //! Allocate a frame of physical memory.
+    //!
+    //! @return An engaged std::optional iff. a new frame could be allocated, std::nullopt otherwise.
+    virtual auto allocate() noexcept -> std::optional<frame> = 0;
+
+    //! Release a frame of physical memory.
+    //!
+    //! @param frame A frame of physical memory, previously acquired by a call to the #allocate function.
     virtual auto release(frame frame) -> void = 0;
+
+  protected:
+    frame_allocator() = default;
   };
 
 }  // namespace teachos::memory