x86_64/memory: improve scoped_mapping docs

1 files changed, 30 insertions, 5 deletions

diff --git a/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp b/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp
index 5737bb0..dff54ec 100644
--- a/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp
+++ b/arch/x86_64/include/x86_64/memory/scoped_mapping.hpp
@@ -8,26 +8,51 @@
 namespace teachos::memory::x86_64
 {
 
+  //! A page mapping that, if established, maps a given frame to a given unused page, unmapping it on destruction. It
+  //! allows for an easy way to quickly map a page that is not required to be mapped forever. When mapping a frame, new
+  //! page tables may be allocated. On destruction, these pages tables, or rather their respective frames, will be
+  //! released again.
   struct scoped_mapping
   {
-    scoped_mapping(scoped_mapping const &) = delete;
-    scoped_mapping(scoped_mapping &&);
+    //! Copying a scoped mapping would be meaningless.
+    scoped_mapping(scoped_mapping const &) noexcept = delete;
+
+    //! Adopt an existing scoped mapping, transferring mapping ownership to this new object.
+    scoped_mapping(scoped_mapping &&) noexcept;
+
+    //! Construct a new scoped mapping, which can be used to map a frame to the given unused page.
+    //! @param page An unused page. If the page is already mapped, this constructor will panic.
+    //! @param allocator An allocator to be used to allocate any page maps required to map the frame.
     scoped_mapping(page page, frame_allocator & allocator);
 
-    ~scoped_mapping();
+    //! Unmap the mapped frame if one was mapped.
+    //! @note Any page tables that were allocated to support the mapping will be released.
+    ~scoped_mapping() noexcept;
 
+    //! Copying a scoped mapping would be meaningless.
     auto operator=(scoped_mapping const &) -> scoped_mapping = delete;
-    auto operator=(scoped_mapping &&) -> scoped_mapping &;
 
+    //! Adopt an existing scoped mapping, swapping mapping ownerships between the objects.
+    auto operator=(scoped_mapping &&) noexcept -> scoped_mapping &;
+
+    //! Map the given frame with the given flags.
+    //! @note If a mapping has already been established, this function will panic
+    //! @param frame A frame to map.
+    //! @param flags The flags, besides the present flag, to apply to the mapping.
+    //! @return A pointer to the first byte of the mapped frame.
     auto map(frame frame, page_table::entry::flags flags) -> std::byte *;
-    auto unmap() -> void;
 
+    //! Map the given frame, returning a typed pointer.
     template<typename DataType>
     auto map_as(frame frame, page_table::entry::flags flags) -> DataType *
     {
       return std::bit_cast<DataType *>(map(frame, flags));
     }
 
+    //! Unmap the mapped frame.
+    //! @note If no frame was ever mapped, this function will panic.
+    auto unmap() -> void;
+
   private:
     page m_page;
     frame_allocator * m_allocator;