docs: add basic documentation for asm_pointer

2 files changed, 50 insertions, 14 deletions

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: