doc: stream documentation for device-paths between uefi-raw and uefi

Author: phip1611

uefi-raw/src/protocol/device_path.rs

@@ -1,5 +1,41 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
+//! UEFI device paths and the UEFI device path protocol.
+//!
+//! This module provides (generated) ABI-compatible bindings to all known device
+//! path node types.
+//!
+//! # Device Paths, Device Path Nodes, and Device Path Instances
+//! A UEFI device path is an open instance of the UEFI device path [protocol],
+//! which can be implemented for any UEFI handle. It is a very flexible
+//! structure for encoding a programmatic path to a device, such as a hard drive
+//! attached to the PCI bus.
+//!
+//! 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
+//! [`END_ENTIRE`] node. A device path _may_ contain multiple device-path
+//! instances separated by [`END_INSTANCE`] nodes, but typical paths contain
+//! only a single instance (in which case no [`END_INSTANCE`] node is needed).
+//!
+//! Example of what a device path containing two instances (each comprised of
+//! three nodes) might look like:
+//!
+//! ```text
+//! ┌──────┬──────┬──────────────╥───────┬──────────┬────────────┐
+//! │ ACPI │ PCI  │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
+//! └──────┴──────┴──────────────╨───────┴──────────┴────────────┘
+//! ↑      ↑      ↑              ↑       ↑          ↑            ↑
+//! ├─Node─╨─Node─╨─────Node─────╨─Node──╨───Node───╨────Node────┤
+//! ↑                            ↑                               ↑
+//! ├─── DevicePathInstance ─────╨────── DevicePathInstance ─────┤
+//! │                                                            │
+//! └──────────────────── Entire DevicePath ─────────────────────┘
+//! ```
+//!
+//! [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
+//! [`END_INSTANCE`]: DeviceSubType::END_INSTANCE
+//! [protocol]: crate::protocol
+
 mod device_path_gen;
 
 use crate::{guid, Boolean, Char16, Guid};

uefi/src/proto/device_path/mod.rs

@@ -1,28 +1,7 @@
 // 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.
-//!
-//! 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
-//! [`END_ENTIRE`] node. A device path _may_ contain multiple device-path
-//! instances separated by [`END_INSTANCE`] nodes, but typical paths contain
-//! only a single instance (in which case no `END_INSTANCE` node is needed).
-//!
-//! Example of what a device path containing two instances (each comprised of
-//! three nodes) might look like:
-//!
-//! ```text
-//! ┌──────┬─────┬──────────────╥───────┬──────────┬────────────┐
-//! │ ACPI │ PCI │ END_INSTANCE ║ CDROM │ FILEPATH │ END_ENTIRE │
-//! └──────┴─────┴──────────────╨───────┴──────────┴────────────┘
-//! ↑                           ↑                               ↑
-//! ├─── DevicePathInstance ────╨────── DevicePathInstance ─────┤
-//! │                                                           │
-//! └─────────────────── Entire DevicePath ─────────────────────┘
-//! ```
+//! High-level wrappers for UEFI [device path](uefi_raw::protocol::device_path)s
+//! and the UEFI device path [`Protocol`].
 //!
 //! # Types
 //!