libs/multiboot2: clean up code style

7 files changed, 208 insertions, 162 deletions

diff --git a/libs/multiboot2/include/multiboot2/constants/architecture_id.hpp b/libs/multiboot2/include/multiboot2/constants/architecture_id.hpp
index 3d560da..e13c471 100644
--- a/libs/multiboot2/include/multiboot2/constants/architecture_id.hpp
+++ b/libs/multiboot2/include/multiboot2/constants/architecture_id.hpp
@@ -14,7 +14,7 @@ namespace multiboot2
     //! 32-bit protected mode i386
     i386 = 0,
     //! 32-bit MIPS
-    MIPS32 = 4,
+    mips32 = 4,
   };
 
 }  // namespace multiboot2
diff --git a/libs/multiboot2/include/multiboot2/constants/information_id.hpp b/libs/multiboot2/include/multiboot2/constants/information_id.hpp
index 7b0fd55..be492eb 100644
--- a/libs/multiboot2/include/multiboot2/constants/information_id.hpp
+++ b/libs/multiboot2/include/multiboot2/constants/information_id.hpp
@@ -8,33 +8,77 @@
 namespace multiboot2
 {
 
-  /**
-   * @brief Information tag IDs.
-   */
+  //! The IDs of all Multiboot2 information tags.
+  //!
+  //! Each tag provided by the boot loader will be tagged with one of these IDs. A tags data format can thus be deduced
+  //! from it's ID.
   enum struct information_id : std::uint32_t
   {
-    END,                    ///< Signals final tag for the multiboot2 information structure.
-    CMDLINE,                ///< Contains the command line string.
-    BOOT_LOADER_NAME,       ///< Contains the name of the boot loader booting the kernel.
-    MODULE,                 ///< Indicates the boot module which was loaded along the kernel image.
-    BASIC_MEMORY_INFO,      ///< Contains the amount of lower (0MB start address) and upper memory (1MB start address).
-    BOOTDEV,                ///< Indicates which BIOS disk device the hoot loader has loaded the OS image from.
-    MEMORY_MAP,             ///< Describes the memory layout of the system with individual areas and their flags.
-    VBE_INFO,               ///< Includes information to access and utilize the device GPU.
-    FRAMEBUFFER,            ///< VBE framebuffer information.
-    ELF_SECTIONS,           ///< Includes list of all section headers from the loaded ELF kernel.
-    APM_INFO,               ///< Advanced Power Management information.
-    EFI32,                  ///< EFI 32 bit system table pointer.
-    EFI64,                  ///< EFI 64 bit system table pointer.
-    SMBIOS,                 ///< Contains copy of all System Management BIOS tables.
-    ACPI_OLD,               ///< Contains copy of RSDP as defined per ACPI1.0 specification.
-    ACPI_NEW,               ///< Contains copy of RSDP as defined per ACPI2.0 or later specification.
-    NETWORK,                ///< Contains network information specified specified as DHCP.
-    EFI_MEMORY_MAP,         ///< Contains EFI memory map.
-    EFI_BS_NOT_TERMINATED,  ///< Indicates ExitBootServices wasn't called.
-    EFI32_IMAGE_HANDLE,     ///< EFI 32 bit image handle pointer.
-    EFI64_IMAGE_HANDLE,     ///< EFI 64 bit image handle pointer.
-    LOAD_BASE_ADDRESS       ///< Contains image load base physical address.
+    //! Signals final tag for the multiboot2 information structure.
+    end,
+
+    //! The command line string.
+    command_line,
+
+    //! The name of the boot loader booting the kernel.
+    boot_loader_name,
+
+    //! Indicates the boot module which was loaded along the kernel image.
+    module,
+
+    //! The amount of lower and upper (above 1 MiB) memory.
+    basic_memory_information,
+
+    //! Indicates which BIOS disk device the hoot loader has loaded the OS image from.
+    boot_device,
+
+    //! Describes the memory layout of the system with individual areas and their flags.
+    memory_map,
+
+    //! Includes information to access and utilize the device GPU.
+    vbe_information,
+
+    //! VBE framebuffer information.
+    framebuferr_information,
+
+    //! Includes list of all section headers from the loaded ELF kernel.
+    elf_sections,
+
+    //! Advanced Power Management information.
+    apm_information,
+
+    //! The pointer to the EFI 32 bit system table.
+    efi32_system_table_pointer,
+
+    //! The pointer to the EFI 64 bit system table.
+    efi64_system_table_pointer,
+
+    //! A copy of all System Management BIOS tables.
+    smbios_tables,
+
+    //! A copy of RSDP as defined per ACPI 1.0 specification.
+    acpi_old_rsdp,
+
+    //! A copy of RSDP as defined per ACPI 2.0 or later specification.
+    acpi_new_rsdp,
+
+    //! The network information specified specified as per DHCP.
+    networking_information,
+
+    //! The memory map as provided by the EFI.
+    efi_memory_map,
+
+    //! Indicates ExitBootServices wasn't called.
+    boot_services_not_terminated,
+
+    //! EFI 32 bit image handle pointer.
+    efi32_image_handle_pointer,
+
+    //! EFI 64 bit image handle pointer.
+    efi64_image_handle_pointer,
+
+    //! The physical image load base address.
+    image_load_base_address
   };
 
 }  // namespace multiboot2
diff --git a/libs/multiboot2/include/multiboot2/constants/memory_type.hpp b/libs/multiboot2/include/multiboot2/constants/memory_type.hpp
index 56fd0b8..6be94bd 100644
--- a/libs/multiboot2/include/multiboot2/constants/memory_type.hpp
+++ b/libs/multiboot2/include/multiboot2/constants/memory_type.hpp
@@ -8,16 +8,24 @@
 namespace multiboot2
 {
 
-  /**
-   * @brief Memory type IDs.
-   */
+  //! The types of memory potentially present in the detailed memory map.
   enum struct memory_type : std::uint32_t
   {
-    AVAILABLE = 1,
-    RESERVED,
-    ACPI_RECLAIMABLE,
-    NON_VOLATILE_STORAGE,
-    BAD_RAM,
+    //! The memory is available for general use by the operating system.
+    available = 1,
+
+    //! The memory is reserved for firmware or other purposes and must not be used for general purposes by the operating
+    //! system.
+    reserved,
+
+    //! The memory contains ACPI data and can be reclaimed when ACPI is not in use.
+    acpi_reclaimable,
+
+    //! The memory is reserved for non-volatile storage.
+    non_volatile_storage,
+
+    //! The memory range is occupied by defective RAM.
+    bad_ram,
   };
 
 }  // namespace multiboot2
diff --git a/libs/multiboot2/include/multiboot2/constants/tag_id.hpp b/libs/multiboot2/include/multiboot2/constants/tag_id.hpp
index 378c2b6..23d39cc 100644
--- a/libs/multiboot2/include/multiboot2/constants/tag_id.hpp
+++ b/libs/multiboot2/include/multiboot2/constants/tag_id.hpp
@@ -8,22 +8,20 @@
 namespace multiboot2
 {
 
-  /**
-   * @brief Header tag IDs.
-   */
+  //! The IDs for tags to be used in the image header.
   enum struct tag_id : std::uint32_t
   {
-    END,
-    INFORMATION_REQUEST,
-    ADDRESSES,
-    ENTRY_ADDRESS,
-    CONSOLE_FLAGS,
-    PREFERRED_FRAMEBUFFER_MODE,
-    PAGE_ALIGN_MODULES,
-    EFI_BOOT_SERVICES_SUPPORTED,
-    EFI32_ENTRY_ADDRESS,
-    EFI64_ENTRY_ADDRESS,
-    RELOCATABLE,
+    end,
+    information_request,
+    addresses,
+    entry_address,
+    console_flags,
+    preferred_framebuffer_mode,
+    page_align_modules,
+    efi_boot_services_supported,
+    efi32_entry_address,
+    efi64_entry_address,
+    relocatable_image,
   };
 
 }  // namespace multiboot2
diff --git a/libs/multiboot2/include/multiboot2/information.hpp b/libs/multiboot2/include/multiboot2/information.hpp
index abb0826..0f48835 100644
--- a/libs/multiboot2/include/multiboot2/information.hpp
+++ b/libs/multiboot2/include/multiboot2/information.hpp
@@ -20,25 +20,25 @@ namespace multiboot2
 {
 
   /**
-   * @copydoc multiboot2::basic_memory_data
+   * @copydoc multiboot2::data::basic_memory
    */
-  struct basic_memory : tag<basic_memory_data>
+  struct basic_memory : tag<data::basic_memory>
   {
     using tag::tag;
   };
 
   /**
-   * @copydoc multiboot2::bios_boot_device_data
+   * @copydoc multiboot2::data::bios_boot_device
    */
-  struct bios_boot_device : tag<bios_boot_device_data>
+  struct bios_boot_device : tag<data::bios_boot_device>
   {
     using tag::tag;
   };
 
   /**
-   * @copydoc multiboot2::command_line_data
+   * @copydoc multiboot2::data::command_line
    */
-  struct command_line : vla_tag<command_line_data, char, std::basic_string_view>
+  struct command_line : vla_tag<data::command_line, char, std::basic_string_view>
   {
     using vla_tag::vla_tag;
 
@@ -52,12 +52,12 @@ namespace multiboot2
   };
 
   /**
-   * @copydoc multiboot2::elf_symbols_data
+   * @copydoc multiboot2::data::elf_symbols
    */
   template<elf::format Format>
-  struct elf_symbols : vla_tag<elf_symbols_data, elf::section_header<Format> const, std::span>
+  struct elf_symbols : vla_tag<data::elf_symbols, elf::section_header<Format> const, std::span>
   {
-    using base = vla_tag<elf_symbols_data, elf::section_header<Format> const, std::span>;
+    using base = vla_tag<data::elf_symbols, elf::section_header<Format> const, std::span>;
     using base::base;
 
     [[nodiscard]] auto name(elf::section_header<Format> const & section) const noexcept -> std::string_view
@@ -75,9 +75,9 @@ namespace multiboot2
   };
 
   /**
-   * @copydoc multiboot2::loader_name_data
+   * @copydoc multiboot2::data::loader_name
    */
-  struct loader_name : vla_tag<loader_name_data, char, std::basic_string_view>
+  struct loader_name : vla_tag<data::loader_name, char, std::basic_string_view>
   {
     using vla_tag::vla_tag;
 
@@ -91,9 +91,9 @@ namespace multiboot2
   };
 
   /**
-   * @copydoc multiboot2::memory_map_data
+   * @copydoc multiboot2::data::memory_map
    */
-  struct memory_map : vla_tag<memory_map_data, memory_map_data::region, std::span>
+  struct memory_map : vla_tag<data::memory_map, data::memory_map::region, std::span>
   {
     using vla_tag::vla_tag;
 
diff --git a/libs/multiboot2/include/multiboot2/information/data.hpp b/libs/multiboot2/include/multiboot2/information/data.hpp
index 38280f8..ccd8fbb 100644
--- a/libs/multiboot2/include/multiboot2/information/data.hpp
+++ b/libs/multiboot2/include/multiboot2/information/data.hpp
@@ -18,120 +18,116 @@ namespace multiboot2
     constexpr auto static inline id = Id;
   };
 
-  /**
-   * @brief Basic system memory information
-   */
-  struct basic_memory_data : tag_data<information_id::BASIC_MEMORY_INFO>
+  namespace data
   {
-    /**
-     * @brief Amount of lower memory (below 1MiB) available to the system.
-     *
-     * The maximum possible value for this field is 640 KiB.
-     */
-    std::uint32_t lower_KiB;
-
-    /**
-     * @brief Amount of upper memory (above 1MiB) available to the system.
-     *
-     * The maximum possible value for this field is the address of the first upper memory hole minus 1MiB.
-     */
-    std::uint32_t upper_KiB;
-  };
 
-  /**
-   * @brief Device the image got loaded from
-   */
-  struct bios_boot_device_data : tag_data<information_id::BOOTDEV>
-  {
-    /**
-     * @brief BIOS device number as understood by INT 13h.
-     */
-    std::uint32_t device_number;
-
-    /**
-     * @brief Number of the primary partition.
-     */
-    std::uint32_t partition_number;
-
-    /**
-     * @brief Number the sub-partition on the primary partition.
-     */
-    std::uint32_t sub_partition_number;
-  };
+    //! Basic system memory information
+    //!
+    //! This tag contains the amount of lower memory and upper memory present in the system as detected by the boot
+    //! loader.
+    struct basic_memory : tag_data<information_id::basic_memory_information>
+    {
+      //! The amount of lower memory available to the system.
+      //!
+      //! Any memory below the 1 MiB address boundary is considered to be lower memory. The maximum possible value for
+      //! this field is 640 KiB.
+      std::uint32_t lower_KiB;
+
+      //! The amount of upper memory available to the system.
+      //!
+      //! Any memory above the 1 MiB address boundary is considered to be upper memory. The maximum possible value for
+      //! this field is the address of the first upper memory hole minus 1MiB.
+      std::uint32_t upper_KiB;
+    };
 
-  /**
-   * @brief Supplied image command line
-   */
-  struct command_line_data : tag_data<information_id::CMDLINE>
-  {
-    /* This struct intentionally left blank. */
-  };
+    //! The BIOS disk the image got loaded from
+    //!
+    //! This tag is present iff. the image was loaded from a BIOS disk device.
+    struct bios_boot_device : tag_data<information_id::boot_device>
+    {
+      //! BIOS device number the image was loaded from, as understood by INT 13h.
+      //!
+      //! For example, the first floppy drive will receive id 0x00, while the first hard disk will receive id 0x80.
+      std::uint32_t device_number;
 
-  /**
-   * @brief ELF symbols of the image
-   */
-  struct elf_symbols_data : tag_data<information_id::ELF_SECTIONS>
-  {
-    std::uint32_t count;
-    std::uint32_t entry_size;
-    std::uint32_t string_table_index;
-  };
+      //! The partition number of the primary partition the image was loaded from.
+      std::uint32_t partition_number;
 
-  /**
-   * @brief Name of the boot loader
-   */
-  struct loader_name_data : tag_data<information_id::BOOT_LOADER_NAME>
-  {
-    /* This struct intentionally left blank. */
-  };
+      //! The sub-partition number of the primary partition the image was loaded from.
+      std::uint32_t sub_partition_number;
+    };
 
-  /**
-   * @brief Detailed map of the memory regions present in the system
-   *
-   */
-  struct memory_map_data : tag_data<information_id::MEMORY_MAP>
-  {
-    /**
-     * @brief A region of memory
-     */
-    struct region
+    //! The command line supplied to the image during boot.
+    //!
+    //! @note This structure is intentionally left blank, since it is of variable size and the contained information
+    //! starts at the first byte of this structure.
+    struct command_line : tag_data<information_id::command_line>
     {
-      /**
-       * @brief Check if the memory described by this region is available for use.
-       */
-      [[nodiscard]] constexpr auto available() const noexcept
-      {
-        return type == memory_type::AVAILABLE;
-      }
+    };
 
-      /**
-       * @brief Start address of this region
-       */
-      std::uint64_t base;
+    //! The ELF sections of the image.
+    //!
+    //! @note The actual section header array is not part of this type's definition. The reason being that the size of
+    //! the array, in terms of entry count, as well as the size and format of each array element is unknown at compile
+    //! time. The array begins after the last member of this structure.
+    struct elf_symbols : tag_data<information_id::elf_sections>
+    {
+      //! The number of section header table entries.
+      std::uint32_t count;
 
-      /**
-       * @brief Size of this region in bytes.
-       */
-      std::uint64_t size_in_B;
+      //! The size of each section header table entry.
+      std::uint32_t entry_size;
 
-      /**
-       * @brief Type of this region.
-       */
-      memory_type type;
+      //! The section number of the string table containing the section names.
+      std::uint32_t string_table_index;
+    };
 
-      std::uint32_t : 0;
+    //! The name of the boot loader that loaded the image.
+    //!
+    //! @note This structure is intentionally left blank, since it is of variable size and the contained information
+    //! starts at the first byte of this structure.
+    struct loader_name : tag_data<information_id::boot_loader_name>
+    {
     };
 
-    /**
-     * @brief Size of each entry present in the map
-     */
-    std::uint32_t entry_size;
+    //! The detailed memory map of this system.
+    struct memory_map : tag_data<information_id::memory_map>
+    {
+      //! A single region of memory
+      struct region
+      {
+        //! Check if the memory described by this region is available for use.
+        [[nodiscard]] constexpr auto available() const noexcept
+        {
+          return type == memory_type::available;
+        }
+
+        //! The physical start address of this region
+        std::uint64_t base;
+
+        //! The size of this region in bytes.
+        std::uint64_t size_in_B;
+
+        //! The type of this region.
+        //!
+        //! @see multiboot::memory_types
+        memory_type type;
+
+        //! This field is reserved for padding and use in future extensions.
+        std::uint32_t : 0;
+      };
+
+      //! The size of each entry present in the map.
+      //!
+      //! This field is present to allow for future extension of the entry format. Each entry's size is guaranteed to
+      //! always be an integer multiple of 8.
+      std::uint32_t entry_size;
+
+      //! The version of each entry present in the map
+      std::uint32_t entry_version;
+    };
 
-    /**
-     * @brief Version of each entry present in the map
-     */
-    std::uint32_t entry_version;
-  };
+  }  // namespace data
 
 }  // namespace multiboot2
 
diff --git a/libs/multiboot2/include/multiboot2/information/iterator.hpp b/libs/multiboot2/include/multiboot2/information/iterator.hpp
index c771933..62c267d 100644
--- a/libs/multiboot2/include/multiboot2/information/iterator.hpp
+++ b/libs/multiboot2/include/multiboot2/information/iterator.hpp
@@ -43,7 +43,7 @@ namespace multiboot2
     {
       if (m_current)
       {
-        if (auto next = m_current.value()->next(); next->information_id() != information_id::END)
+        if (auto next = m_current.value()->next(); next->information_id() != information_id::end)
         {
           m_current = next;
         }