From 582e88c060909136d1f1d90a755ada2d47d12659 Mon Sep 17 00:00:00 2001
From: Felix Morgner <felix.morgner@ost.ch>
Date: Mon, 15 Dec 2025 17:26:47 +0100
Subject: libs/elf: fix documentation

---
 libs/elf/include/elf/format.hpp         |  4 ++++
 libs/elf/include/elf/section_header.hpp | 27 ++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/libs/elf/include/elf/format.hpp b/libs/elf/include/elf/format.hpp
index b3220f5..bc85101 100644
--- a/libs/elf/include/elf/format.hpp
+++ b/libs/elf/include/elf/format.hpp
@@ -4,6 +4,10 @@
 namespace elf
 {
 
+  //! The format of the ELF file being processed.
+  //!
+  //! Certain information structures in the ELF are heavily dependent on the bitness of the target architecture. The
+  //! values of this enumeration type are used to distinguish between the different variants.
   enum struct format
   {
     elf32,
diff --git a/libs/elf/include/elf/section_header.hpp b/libs/elf/include/elf/section_header.hpp
index 3afe334..2b907cb 100644
--- a/libs/elf/include/elf/section_header.hpp
+++ b/libs/elf/include/elf/section_header.hpp
@@ -3,6 +3,7 @@
 
 #include "format.hpp"
 
+#include <cstddef>
 #include <cstdint>
 #include <limits>
 #include <type_traits>
@@ -11,20 +12,39 @@
 namespace elf
 {
 
+  //! The platform dependent header size.
+  //!
+  //! The size of a section header table in ELF is dependent on the bitness of the platform the file is designed for.
+  //! This constant allows compile-time parametrization of objects and functions for a specific architecture.
   template<format Format>
   constexpr auto inline section_header_size = std::numeric_limits<std::size_t>::max();
 
+  //! @copydoc elf::section_header_size
+  //!
+  //! @note This specialization provides the section header size for 32-bit ELF files.
   template<>
   constexpr auto inline section_header_size<format::elf32> = 40uz;
 
+  //! @copydoc elf::section_header_size
+  //!
+  //! @note This specialization provides the section header size for 64-bit ELF files.
   template<>
   constexpr auto inline section_header_size<format::elf64> = 64uz;
 
+  //! An ELF section header table entry.
+  //!
+  //! In the ELF, the section header table describes the layout and properties of the sections present in the loadable
+  //! files. This information is used to map and load data from the file according to their use.
   template<format Format>
   struct section_header
   {
+    //! A platform dependent unsigned integer.
+    //!
+    //! The size of certain fields in a section header of the ELF is dependent on the bitness of the target platform,
+    //! accounting for the differing sizes of 32 and 64 bit section header table entries.
     using format_uint = std::conditional_t<Format == format::elf32, std::uint32_t, std::uint64_t>;
 
+    //! The type of the section described by this header.
     enum struct header_type : std::uint32_t
     {
       null = 0,                                ///< Is inactive
@@ -46,9 +66,10 @@ namespace elf
       extended_section_header_indices = 18,    ///< Contains extended section header indices
     };
 
+    //! The properties of the section describe by this header.
     enum struct header_flags : format_uint
     {
-      writeable = 0x1,               ///< Contains writable data
+      writable = 0x1,                ///< Contains writable data
       allocated = 0x2,               ///< Occupies memory during execution
       executable = 0x4,              ///< Contains executable instructions
       mergeable = 0x10,              ///< Contained data may be merged for deduplication
@@ -73,10 +94,10 @@ namespace elf
       return std::to_underlying(flags) & std::to_underlying(header_flags::executable);
     }
 
-    //! Check if the section is writeable
+    //! Check if the section is writable
     [[nodiscard]] constexpr auto writable() const noexcept -> bool
     {
-      return std::to_underlying(flags) & std::to_underlying(header_flags::writeable);
+      return std::to_underlying(flags) & std::to_underlying(header_flags::writable);
     }
 
     std::uint32_t name_offset;         ///< Offset into the section header string table, defining the section name
-- 
cgit v1.2.3