2 files changed, 63 insertions, 2 deletions

diff --git a/embassy-boot/src/boot_loader.rs b/embassy-boot/src/boot_loader.rs
index c433ce439..2a5f024f6 100644
--- a/embassy-boot/src/boot_loader.rs
+++ b/embassy-boot/src/boot_loader.rs
@@ -56,7 +56,38 @@ impl<'a, ACTIVE: NorFlash, DFU: NorFlash, STATE: NorFlash>
         BlockingPartition<'a, NoopRawMutex, STATE>,
     >
 {
-    /// Create a bootloader config from the flash and address symbols defined in the linkerfile
+    /// Constructs a `BootLoaderConfig` instance from flash memory and address symbols defined in the linker file.
+    ///
+    /// This method initializes `BlockingPartition` instances for the active, DFU (Device Firmware Update),
+    /// and state partitions, leveraging start and end addresses specified by the linker. These partitions
+    /// are critical for managing firmware updates, application state, and boot operations within the bootloader.
+    ///
+    /// # Parameters
+    /// - `active_flash`: A reference to a mutex-protected `RefCell` for the active partition's flash interface.
+    /// - `dfu_flash`: A reference to a mutex-protected `RefCell` for the DFU partition's flash interface.
+    /// - `state_flash`: A reference to a mutex-protected `RefCell` for the state partition's flash interface.
+    ///
+    /// # Safety
+    /// The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses
+    /// of the bootloader's partitions in flash memory. It is crucial that these addresses are accurately defined
+    /// in the memory.x file to prevent undefined behavior.
+    ///
+    /// The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory
+    /// interfaces provided are compatible with these regions.
+    ///
+    /// # Returns
+    /// A `BootLoaderConfig` instance with `BlockingPartition` instances for the active, DFU, and state partitions.
+    ///
+    /// # Example
+    /// ```no_run
+    /// // Assume `active_flash`, `dfu_flash`, and `state_flash` all share the same flash memory interface.
+    /// let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
+    /// let flash = Mutex::new(RefCell::new(layout.bank1_region));
+    ///
+    /// let config = BootLoaderConfig::from_linkerfile_blocking(&flash, &flash, &flash);
+    /// // `config` can now be used to create a `BootLoader` instance for managing boot operations.
+    /// ```
+    /// Working examples can be found in the bootloader examples folder.
     // #[cfg(target_os = "none")]
     pub fn from_linkerfile_blocking(
         active_flash: &'a Mutex<NoopRawMutex, RefCell<ACTIVE>>,
diff --git a/embassy-boot/src/firmware_updater/blocking.rs b/embassy-boot/src/firmware_updater/blocking.rs
index cf850fce3..a29efabf0 100644
--- a/embassy-boot/src/firmware_updater/blocking.rs
+++ b/embassy-boot/src/firmware_updater/blocking.rs
@@ -19,7 +19,37 @@ pub struct BlockingFirmwareUpdater<'d, DFU: NorFlash, STATE: NorFlash> {
 impl<'a, DFU: NorFlash, STATE: NorFlash>
     FirmwareUpdaterConfig<BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>
 {
-    /// Create a firmware updater config from the flash and address symbols defined in the linkerfile
+    /// Constructs a `FirmwareUpdaterConfig` instance from flash memory and address symbols defined in the linker file.
+    ///
+    /// This method initializes `BlockingPartition` instances for the DFU (Device Firmware Update), and state
+    /// partitions, leveraging start and end addresses specified by the linker. These partitions are critical
+    /// for managing firmware updates, application state, and boot operations within the bootloader.
+    ///
+    /// # Parameters
+    /// - `dfu_flash`: A reference to a mutex-protected `RefCell` for the DFU partition's flash interface.
+    /// - `state_flash`: A reference to a mutex-protected `RefCell` for the state partition's flash interface.
+    ///
+    /// # Safety
+    /// The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses
+    /// of the bootloader's partitions in flash memory. It is crucial that these addresses are accurately defined
+    /// in the memory.x file to prevent undefined behavior.
+    ///
+    /// The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory
+    /// interfaces provided are compatible with these regions.
+    ///
+    /// # Returns
+    /// A `FirmwareUpdaterConfig` instance with `BlockingPartition` instances for the DFU, and state partitions.
+    ///
+    /// # Example
+    /// ```no_run
+    /// // Assume `dfu_flash`, and `state_flash` share the same flash memory interface.
+    /// let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
+    /// let flash = Mutex::new(RefCell::new(layout.bank1_region));
+    ///
+    /// let config = FirmwareUpdaterConfig::from_linkerfile_blocking(&flash, &flash);
+    /// // `config` can now be used to create a `FirmwareUpdater` instance for managing boot operations.
+    /// ```
+    /// Working examples can be found in the bootloader examples folder.
     pub fn from_linkerfile_blocking(
         dfu_flash: &'a embassy_sync::blocking_mutex::Mutex<NoopRawMutex, core::cell::RefCell<DFU>>,
         state_flash: &'a embassy_sync::blocking_mutex::Mutex<NoopRawMutex, core::cell::RefCell<STATE>>,