docs: add basic documentation for asm_pointer

6 files changed, 82 insertions, 14 deletions

diff --git a/docs/cross.rst b/docs/cross.rst
new file mode 100644
index 0000000..542d76a
--- /dev/null
+++ b/docs/cross.rst
@@ -0,0 +1,9 @@
+Platform-Independent Infrastructure
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+   :glob:
+
+   cross/*
diff --git a/docs/cross/memory.rst b/docs/cross/memory.rst
new file mode 100644
index 0000000..3a2c1c4
--- /dev/null
+++ b/docs/cross/memory.rst
@@ -0,0 +1,11 @@
+Memory Access and Management
+============================
+
+This sections details the platform-**independent** infrastructure for memory access and management.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :caption: Types:
+
+   memory/*
diff --git a/docs/cross/memory/asm_pointer.rst b/docs/cross/memory/asm_pointer.rst
new file mode 100644
index 0000000..70f5c01
--- /dev/null
+++ b/docs/cross/memory/asm_pointer.rst
@@ -0,0 +1,10 @@
+Access to Pointers Defined in Assembly
+======================================
+
+.. doxygenstruct:: teachos::memory::asm_pointer
+   :members:
+
+Specializations
+---------------
+
+.. doxygenstruct:: teachos::memory::asm_pointer< Type const >
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 44e7617..a804c88 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,6 +5,8 @@ Welcome to TeachOS Kernel's documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   cross
+
 Indices and tables
 ==================
 
diff --git a/source/CMakeLists.txt b/source/CMakeLists.txt
index 215dd39..beb0c07 100644
--- a/source/CMakeLists.txt
+++ b/source/CMakeLists.txt
@@ -29,26 +29,35 @@ set(DOXYGEN_QUIET YES)
 
 file(GLOB_RECURSE DOXYGEN_SOURCES CONFIGURE_DEPENDS "*.hpp")
 
-doxygen_add_docs("docs"
+message(STATUS "${SPHINX_SOURCES}")
+
+doxygen_add_docs("docs_xml"
   ${DOXYGEN_SOURCES}
   ALL
   USE_STAMP_FILE
   COMMENT "Generating developer documentation sources"
 )
 
-add_custom_command(TARGET "docs"
-  POST_BUILD
+set_target_properties("docs_xml" PROPERTIES
+  ADDITIONAL_CLEAN_FILES
+  "${PROJECT_BINARY_DIR}/doxygen"
+)
+
+file(GLOB_RECURSE SPHINX_SOURCES CONFIGURE_DEPENDS "../docs/**.rst") 
+
+add_custom_target("docs" ALL
   COMMAND "${SPHINX_BUILD_EXE}"
-  ARGS
   "../docs"
   "docs"
   "-q"
+  DEPENDS "docs_xml"
+  SOURCES ${SPHINX_SOURCES}
   COMMENT "Generating developer documentation html"
 )
 
 set_target_properties("docs" PROPERTIES
   ADDITIONAL_CLEAN_FILES
-  "${PROJECT_BINARY_DIR}/doxygen;${PROJECT_BINARY_DIR}/docs"
+  "${PROJECT_BINARY_DIR}/docs"
 )
 
 #[============================================================================[
diff --git a/source/include/memory/asm_pointer.hpp b/source/include/memory/asm_pointer.hpp
index 2001561..9ec2218 100644
--- a/source/include/memory/asm_pointer.hpp
+++ b/source/include/memory/asm_pointer.hpp
@@ -4,36 +4,63 @@
 namespace teachos::memory
 {
 
+  /**
+   * @brief A pointer that is defined in some assembly source file.
+   *
+   * @tparam Type The type of the pointer
+   * @since 0.0.1
+   */
   template<typename Type>
   struct asm_pointer
   {
-    using pointer = Type;
+    /**
+     * @brief The type of the underlying pointer.
+     */
+    using pointer = Type *;
 
-    constexpr asm_pointer(Type & pointer)
+    /**
+     * @brief Construct a new asm_pointer for a given assembly-defined pointer.
+     * @param pointer A pointer defined in assembly.
+     */
+    constexpr asm_pointer(Type *& pointer)
         : m_pointer{&pointer}
     {
     }
 
-    auto constexpr operator->() -> Type * { return m_pointer; }
-    auto constexpr operator->() const -> Type const * { return m_pointer; }
-    auto constexpr operator*() -> Type & { return *m_pointer; }
-    auto constexpr operator*() const -> Type const & { return *m_pointer; }
+    /**
+     * @brief Access the underlying pointer.
+     * @return The pointer wrapped by this asm_pointer.
+     */
+    auto constexpr operator*() -> pointer & { return *m_pointer; }
+
+    /**
+     * @brief Access the underlying pointer.
+     * @return The pointer wrapped by this asm_pointer.
+     */
+    auto constexpr operator*() const -> pointer const & { return *m_pointer; }
 
   private:
-    Type * m_pointer;
+    pointer * m_pointer;
   };
 
+  /**
+   * @copydoc asm_pointer
+   *
+   * @note This specialization allows the use of this type for pointers to constant data.
+   * @since 0.0.1
+   */
   template<typename Type>
   struct asm_pointer<Type const>
   {
+    /** @copydoc asm_pointer<Type>::asm_pointer */
     constexpr asm_pointer(Type const & pointer)
         : m_pointer{&pointer}
     {
     }
 
-    auto constexpr operator->() -> Type const * { return m_pointer; }
-    auto constexpr operator->() const -> Type const * { return m_pointer; }
+    /** @copydoc asm_pointer<Type>::operator*() */
     auto constexpr operator*() -> Type const & { return *m_pointer; }
+    /** @copydoc asm_pointer<Type>::operator*() const */
     auto constexpr operator*() const -> Type const & { return *m_pointer; }
 
   private: