From 2fc8c17b9e7553dc0dcd4ca798aebe27c8a10db0 Mon Sep 17 00:00:00 2001
From: Philipp Schuster <phip1611@gmail.com>
Date: Sun, 9 Nov 2025 17:28:38 +0100
Subject: [PATCH] uefi: improve doc

---
 uefi/src/proto/device_path/build.rs |  3 ++-
 uefi/src/proto/device_path/mod.rs   | 16 +++++++++++++++-
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/uefi/src/proto/device_path/build.rs b/uefi/src/proto/device_path/build.rs
index 66efe2c2..3adcb742 100644
--- a/uefi/src/proto/device_path/build.rs
+++ b/uefi/src/proto/device_path/build.rs
@@ -99,7 +99,7 @@ impl<'a> DevicePathBuilder<'a> {
     /// Add a node to the device path.
     ///
     /// An error will be returned if an [`END_ENTIRE`] node is passed to
-    /// this function, as that node will be added when `finalize` is
+    /// this function, as that node will be added when [`Self::finalize`] is
     /// called.
     ///
     /// [`END_ENTIRE`]: uefi::proto::device_path::DeviceSubType::END_ENTIRE
@@ -150,6 +150,7 @@ impl<'a> DevicePathBuilder<'a> {
     }
 }
 
+/// Reference to the backup storage for [`DevicePathBuilder`]
 #[derive(Debug)]
 enum BuilderStorage<'a> {
     Buf {
diff --git a/uefi/src/proto/device_path/mod.rs b/uefi/src/proto/device_path/mod.rs
index 53953bab..01c151f6 100644
--- a/uefi/src/proto/device_path/mod.rs
+++ b/uefi/src/proto/device_path/mod.rs
@@ -75,6 +75,8 @@
 //!   other types in this module are DSTs, so pointers to the type are
 //!   "fat" and not suitable for FFI.
 //!
+//! * [`PoolDevicePath`] is an owned device path on the UEFI heap.
+//!
 //! All of these types use a packed layout and may appear on any byte
 //! boundary.
 //!
@@ -134,6 +136,10 @@ opaque_type! {
 }
 
 /// Device path allocated from UEFI pool memory.
+///
+/// Please note that this differs from <code>Box<[DevicePath]></code>. Although
+/// both represent owned values, a <code>Box<[DevicePath]></code> is on the Rust
+/// heap which may or may not be backed by the UEFI heap.
 #[derive(Debug)]
 pub struct PoolDevicePath(pub(crate) PoolAllocation);
 
@@ -408,11 +414,15 @@ impl DevicePathInstance {
     }
 
     /// Returns a boxed copy of that value.
+    ///
+    /// The semantics slightly differs from a [`PoolDevicePath`] but is
+    /// generally more idiomatic to use.
     #[cfg(feature = "alloc")]
     #[must_use]
     pub fn to_boxed(&self) -> Box<Self> {
         let data = self.data.to_owned();
         let data = data.into_boxed_slice();
+        // SAFETY: This is safe as a DevicePath has the same layout.
         unsafe { mem::transmute(data) }
     }
 }
@@ -595,12 +605,16 @@ impl DevicePath {
         &self.data
     }
 
-    /// Returns a boxed copy of that value.
+    /// Returns a boxed copy of that value on the Rust heap.
+    ///
+    /// The semantics slightly differs from a [`PoolDevicePath`] but is
+    /// generally more idiomatic to use.
     #[cfg(feature = "alloc")]
     #[must_use]
     pub fn to_boxed(&self) -> Box<Self> {
         let data = self.data.to_owned();
         let data = data.into_boxed_slice();
+        // SAFETY: This is safe as a DevicePath has the same layout.
         unsafe { mem::transmute(data) }
     }