doc/uefi: improve device path documentation

Make the role of the high-level DevicePath wrapper more clear.

Author: phip1611

uefi/src/proto/device_path/mod.rs

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Device Path protocol
-//!
-//! A UEFI device path is a very flexible structure for encoding a
-//! programmatic path such as a hard drive or console.
+//! Helpers to work with UEFI Device Paths and the Device Path Protocol 
+//! 
+//! The main export of this module is [`DevicePath`].
 //!
 //! A device path is made up of a packed list of variable-length nodes of
 //! various types. The entire device path is terminated with an
@@ -346,19 +345,43 @@ impl ToOwned for DevicePathInstance {
     }
 }
 
-/// Device path protocol.
+/// Type representing a UEFI device path and also implementing the UEFI 
+/// protocol.
+///
+/// A UEFI device path is a structured sequence of binary nodes that describe a
+/// route from the UEFI root to a particular device, controller, or file. Each
+/// node represents a step in the path: PCI device, partition, filesystem, file
+/// path, etc.
 ///
-/// Can be used on any device handle to obtain generic path/location information
-/// concerning the physical device or logical device. If the handle does not
-/// logically map to a physical device, the handle may not necessarily support
-/// the device path protocol. The device path describes the location of the
-/// device the handle is for. The size of the Device Path can be determined from
-/// the structures that make up the Device Path.
+/// This type implements [`DevicePathProtocol`] and therefore can be used on any
+/// device handle to obtain generic path/location information concerning the
+/// physical device or logical device. If the handle does not logically map to a
+/// physical device, the handle may not necessarily support the device path
+/// protocol. The device path describes the location of the device the handle is
+/// for. The size of the Device Path can be determined from the structures that
+/// make up the Device Path.
 ///
 /// See the [module-level documentation] for more details.
 ///
+/// # Example
+/// ```rust
+/// use uefi::Handle;
+/// use uefi::boot::{open_protocol_exclusive, ScopedProtocol};
+/// use uefi::proto::device_path::DevicePath;
+/// use uefi::proto::loaded_image::LoadedImage;
+///
+/// fn open_device_path(image_handle: Handle) {
+///     let loaded_image = open_protocol_exclusive::<LoadedImage>(image_handle).unwrap();
+///     let device_handle = loaded_image .device().unwrap();
+///     // We use `DevicePath` as protocol and also as return type.
+///     let device_path: ScopedProtocol<DevicePath>
+///         = open_protocol_exclusive::<DevicePath>(device_handle).unwrap();
+/// }
+/// ```
+///
 /// [module-level documentation]: crate::proto::device_path
 /// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
+/// [`DevicePathProtocol`]: uefi_raw::protocol::device_path::DevicePathProtocol
 #[repr(C, packed)]
 #[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
 #[derive(Eq, Pointee)]