x86_64: improve linker script interface docs

- Add file-level Doxygen block to provide overall context.
- Clarify the origin of the declared symbols.
- Add information regarding their intended use.

1 files changed, 38 insertions, 13 deletions

diff --git a/arch/x86_64/include/x86_64/boot/ld.hpp b/arch/x86_64/include/x86_64/boot/ld.hpp
index e6b397b..6051dd7 100644
--- a/arch/x86_64/include/x86_64/boot/ld.hpp
+++ b/arch/x86_64/include/x86_64/boot/ld.hpp
@@ -1,22 +1,47 @@
+/**
+ * @file
+ * @brief Provides an interface to linker script defined symbols.
+ *
+ * @details
+ * This header provides declarations for symbols that are defined in the linker script itself. The symbols declared here
+ * provide important information, for example the start and end of the kernel image in physical memory.
+ *
+ * Any variables defined in this file must not be read themselves, but rather their address shall be taken, yielding a
+ * pointer to the memory location the represent.
+ *
+ * @see arch/x86_64/scripts/kernel.ld
+ */
+
 #ifndef TEACHOS_X86_64_BOOT_LD_H
 #define TEACHOS_X86_64_BOOT_LD_H
 
 #include <cstddef>
 
-extern "C"
+namespace teachos::x86_64::boot
 {
-  namespace teachos::x86_64::boot
-  {
-    /**
-     * @brief The first byte of the loaded kernel image.
-     */
-    extern "C" std::byte _start_linear;
+  /**
+   * @var _start_linear
+   * @brief The first byte of the loaded kernel image.
+   *
+   * @details
+   * This symbols is defined in the kernel linker script and marks the start of the kernel image in physical memory.
+   * To use this symbol for its intended purpose, the address of it shall be taken.
+   *
+   * @see _end_linear
+   */
+  extern "C" std::byte _start_linear;
 
-    /**
-     * @brief The first byte after the loaded kernel image.
-     */
-    extern "C" std::byte _end_linear;
-  }  // namespace teachos::x86_64::boot
-}
+  /**
+   * @var _end_linear
+   * @brief The first byte after the loaded kernel image.
+   *
+   * @details
+   * This symbols is defined in the kernel linker script and marks the end of the kernel image in physical memory.
+   * To use this symbol for its intended purpose, the address of it shall be taken.
+   *
+   * @see _start_linear
+   */
+  extern "C" std::byte _end_linear;
+}  // namespace teachos::x86_64::boot
 
 #endif