add comments

6 files changed, 187 insertions, 1 deletions

diff --git a/kernel/devices/include/devices/block_device.hpp b/kernel/devices/include/devices/block_device.hpp
index 240cb3b..78a2606 100644
--- a/kernel/devices/include/devices/block_device.hpp
+++ b/kernel/devices/include/devices/block_device.hpp
@@ -7,15 +7,49 @@
 
 namespace devices
 {
+  /**
+   * @brief Base interface for block-addressable devices.
+   */
   struct block_device : device
   {
+    /**
+     * @brief Create a block device descriptor.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     * @param block_size Size of one logical block in bytes.
+     */
     block_device(size_t major, size_t minor, size_t block_size);
+
+    /**
+     * @brief Virtual destructor for block device.
+     */
     virtual ~block_device() = default;
 
+    /**
+     * @brief Read data from the block at @p block_index into @p buffer.
+     * @param block_index Zero-based block index.
+     * @param buffer Destination buffer.
+     * @warning Panics if @p buffer is null.
+     * @note Reads up to one logical block (see constructor @p block_size). Implementations may perform a partial
+     * transfer for the final block when fewer than @p block_size bytes remain.
+     */
     virtual auto read_block(size_t block_index, void * buffer) const -> void = 0;
+
+    /**
+     * @brief Write data to the block at @p block_index.
+     * @param block_index Zero-based block index.
+     * @param buffer Source buffer, must not be null.
+     * @warning Panics if @p buffer is null.
+     * @note Writes up to one logical block (see constructor @p block_size).
+     * Implementations may perform a partial transfer for the final block when
+     * fewer than @p block_size bytes remain.
+     */
     virtual auto write_block(size_t block_index, void const * buffer) -> void = 0;
 
   protected:
+    /**
+     * @brief Information describing the transfer window for one block index.
+     */
     struct transfer_info
     {
       size_t offset;
@@ -23,7 +57,17 @@ namespace devices
       size_t remainder;
     };
 
+    /**
+     * @brief Return total device size in bytes.
+     * @return Total number of addressable bytes.
+     */
     virtual auto size() const -> size_t = 0;
+
+    /**
+     * @brief Compute transfer information for @p block_index.
+     * @param block_index Zero-based block index.
+     * @return Computed transfer information for one logical block access.
+     */
     auto calculate_transfer(size_t block_index) const -> transfer_info;
 
     size_t m_block_size;
diff --git a/kernel/devices/include/devices/device.hpp b/kernel/devices/include/devices/device.hpp
index 0f93bff..cbf77c2 100644
--- a/kernel/devices/include/devices/device.hpp
+++ b/kernel/devices/include/devices/device.hpp
@@ -5,17 +5,39 @@
 
 namespace devices
 {
+  /**
+   * @brief Base device identified by a major and minor number.
+   */
   struct device
   {
+    /**
+     * @brief Create a device identifier from @p major and @p minor.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     */
     device(size_t major, size_t minor);
+
+    /**
+     * @brief Virtual destructor for device.
+     */
     virtual ~device() = default;
 
+    /**
+     * @brief Returns the major number of the device.
+     * @return Device major number.
+     */
     auto major() const -> size_t;
+
+    /**
+     * @brief Returns the minor number of the device.
+     * @return Device minor number.
+     */
     auto minor() const -> size_t;
 
   private:
     size_t m_major;
     size_t m_minor;
+    // TODO BA-FS26 add name
   };
 }  // namespace devices
 
diff --git a/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp b/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp
index f050ba0..05cac88 100644
--- a/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp
+++ b/kernel/devices/include/devices/storage/ram_disk/ram_disk_controller.hpp
@@ -12,17 +12,39 @@
 
 namespace devices::storage::ram_disk
 {
+  /**
+   * @brief Storage controller that exposes boot modules as RAM-disk devices.
+   */
   struct ram_disk_controller : storage_controller
   {
+    /**
+     * @brief Create a RAM-disk controller.
+     * @param registry Boot module registry as device source.
+     */
     explicit ram_disk_controller(kapi::boot_modules::boot_module_registry const * registry);
 
+    /**
+     * @brief Probe boot modules and create RAM-disk devices.
+     */
     auto probe() -> void override;
 
+    /**
+     * @brief Return the number of managed RAM-disk devices.
+     * @return Number of managed devices.
+     */
     auto devices_count() -> size_t override;
+
+    /**
+     * @brief Look up a RAM-disk device by major/minor numbers.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     * @return Matching block device, or nullptr if no device matches.
+     */
     auto device_by_major_minor(size_t major, size_t minor) -> block_device * override;
 
   private:
     kapi::boot_modules::boot_module_registry const * m_boot_module_registry;
+
     std::array<ram_disk_device, 1> m_devices{};  // TODO BA-FS26 use kstd::vector when available
   };
 }  // namespace devices::storage::ram_disk
diff --git a/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp b/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp
index 1f0292f..eebbcd7 100644
--- a/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp
+++ b/kernel/devices/include/devices/storage/ram_disk/ram_disk_device.hpp
@@ -9,15 +9,42 @@
 
 namespace devices::storage::ram_disk
 {
+  /**
+   * @brief Block device for a boot module.
+   */
   struct ram_disk_device : block_device
   {
     ram_disk_device();  // TODO BA-FS26 remove when kstd::vector is available
+
+    /**
+     * @brief Create a RAM disk for the @p module.
+     * @param module Boot module providing the memory region.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     */
     ram_disk_device(kapi::boot_modules::boot_module const & module, size_t major, size_t minor);
 
+    /**
+     * @brief Read one logical block into @p buffer.
+     * @param block_index Zero-based block index.
+     * @param buffer Destination buffer, must not be null.
+     * @note If the request reaches the module end, only available bytes are copied and the rest of the
+     * logical block is filled with zeros.
+     */
     auto read_block(size_t block_index, void * buffer) const -> void override;
+
+    /**
+     * @brief Write one logical block from @p buffer.
+     * @param block_index Zero-based block index.
+     * @param buffer Source buffer, must not be null.
+     * @note If the request reaches the module end, only the bytes in the module range are written.
+     */
     auto write_block(size_t block_index, void const * buffer) -> void override;
 
   private:
+    /**
+     * @brief Return module size in bytes.
+     */
     auto size() const -> size_t override;
 
     kapi::boot_modules::boot_module m_boot_module{};
diff --git a/kernel/devices/include/devices/storage/storage_controller.hpp b/kernel/devices/include/devices/storage/storage_controller.hpp
index 0c09815..18c7232 100644
--- a/kernel/devices/include/devices/storage/storage_controller.hpp
+++ b/kernel/devices/include/devices/storage/storage_controller.hpp
@@ -7,16 +7,49 @@
 
 namespace devices::storage
 {
+  /**
+   * @brief Base interface for storage controllers.
+   *
+   * A storage controller probes for devices and resolves devices by major/minor
+   * numbers.
+   */
   struct storage_controller
   {
+    /**
+     * @brief Virtual destructor.
+     */
     virtual ~storage_controller() = default;
 
+    /**
+     * @brief Probe the controller and register discovered devices.
+     */
     virtual auto probe() -> void = 0;
 
+    /**
+     * @brief Assign the major number and minor stride for this controller.
+     * @param major Major number assigned to this controller.
+     * @param minors_per_dev Minor number stride between devices.
+     */
     auto set_ids(size_t major, size_t minors_per_dev) -> void;
+
+    /**
+     * @brief Return the assigned major number.
+     * @return Assigned major number.
+     */
     auto major() const -> size_t;
 
+    /**
+     * @brief Return the number of devices managed by this controller.
+     * @return Number of managed devices.
+     */
     virtual auto devices_count() -> size_t = 0;
+
+    /**
+     * @brief Find a managed device by major/minor numbers.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     * @return Matching block device, or nullptr if no device matches.
+     */
     virtual auto device_by_major_minor(size_t major, size_t minor) -> block_device * = 0;
 
   protected:
diff --git a/kernel/devices/include/devices/storage/storage_management.hpp b/kernel/devices/include/devices/storage/storage_management.hpp
index c4f5679..2bed459 100644
--- a/kernel/devices/include/devices/storage/storage_management.hpp
+++ b/kernel/devices/include/devices/storage/storage_management.hpp
@@ -9,19 +9,57 @@
 
 namespace devices::storage
 {
-  // TODO BA-FS26 add documentation
+  /**
+   * @brief Global storage subsystem manager.
+   *
+   * Owns registered storage controllers and provides device lookup by
+   * major/minor numbers.
+   */
   struct storage_management
   {
+    /**
+     * @brief Initialize global storage management.
+     *
+     * Creates the singleton instance, registers controllers and probes
+     * them for devices.
+     *
+     * @warning Panics if called more than once.
+     */
     auto static init() -> void;
 
+    /**
+     * @brief Return the active storage manager singleton.
+     * @return Reference to the active storage manager.
+     * @warning Panics if storage management has not been initialized.
+     */
     auto static get() -> storage_management &;
 
+    /**
+     * @brief Register a storage controller.
+     * @param controller Controller to register.
+     *
+     * Assigns controller IDs (major number range and minors per device).
+     */
     auto add_controller(storage_controller * controller) -> void;
 
+    /**
+     * @brief Find a block device by major/minor numbers.
+     * @param major Device major number.
+     * @param minor Device minor number.
+     * @return Matching block device, or nullptr if no device matches.
+     */
     auto device_by_major_minor(size_t major, size_t minor) -> block_device *;
+
+    /**
+     * @brief Determine the boot device.
+     * @return Boot device, or nullptr if it cannot be determined.
+     */
     auto determine_boot_device() -> block_device *;
 
   private:
+    /**
+     * @brief Private default constructor for storage management singleton.
+     */
     storage_management() = default;
 
     std::array<storage_controller *, 1> m_controllers{};  // TODO BA-FS26 use kstd::vector when available