uefi/raw: streamline documentation of Protocol

We don't deduplicate everything and keep a few important things
in uefi as well. See #1641 (comment) for a discussion.

Author: phip1611

uefi-raw/src/protocol/mod.rs

@@ -2,9 +2,26 @@
 
 //! Protocol definitions.
 //!
-//! Protocols are sets of related functionality identified by a unique
-//! ID. They can be implemented by a UEFI driver or occasionally by a
-//! UEFI application.
+//! # TL;DR
+//! Technically, a protocol is a `C` struct holding functions and/or data, with
+//! an associated [`GUID`].
+//!
+//! # About
+//! UEFI protocols are a structured collection of functions and/or data,
+//! identified by a [`GUID`], which defines an interface between components in
+//! the UEFI environment, such as between drivers, applications, or firmware
+//! services.
+//!
+//! Protocols are central to UEFI’s handle-based object model, and they provide
+//! a clean, extensible way for components to discover and use services from one
+//! another.
+//!
+//! Implementation-wise, a protocol is a `C` struct holding function pointers
+//! and/or data. Please note that some protocols may use [`core::ptr::null`] as
+//! interface. For example, the device path protocol can be implemented but
+//! return `null`.
+//!
+//! [`GUID`]: crate::Guid
 
 pub mod ata;
 pub mod block;

uefi/src/proto/mod.rs

@@ -1,14 +1,35 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Protocol definitions.
+//! High-level wrappers for [UEFI protocols].
 //!
-//! Protocols are sets of related functionality identified by a unique
-//! ID. They can be implemented by a UEFI driver or occasionally by a
-//! UEFI application.
+//! # TL;DR
+//! Technically, a protocol is a `C` struct holding functions and/or data, with
+//! an associated [`GUID`].
 //!
-//! See the [`boot`] documentation for details of how to open a protocol.
+//! # About
+//! UEFI protocols are a structured collection of functions and/or data,
+//! identified by a [`GUID`], which defines an interface between components in
+//! the UEFI environment, such as between drivers, applications, or firmware
+//! services.
+//!
+//! Protocols are central to UEFI’s handle-based object model, and they provide
+//! a clean, extensible way for components to discover and use services from one
+//! another.
+//!
+//! Implementation-wise, a protocol is a `C` struct holding function pointers
+//! and/or data. Please note that some protocols may use [`core::ptr::null`] as
+//! interface. For example, the device path protocol can be implemented but
+//! return `null`.
+//!
+//! [`GUID`]: crate::Guid
+//!
+//! # More Info
+//! - See the [`boot`] documentation for details of how to open a protocol.
+//! - Please find additional low-level information in the
+//!   [protocol section of `uefi-raw`][[UEFI protocols]].
 //!
 //! [`boot`]: crate::boot#accessing-protocols
+//! [UEFI protocols]: uefi_raw::protocol
 
 #[cfg(feature = "alloc")]
 pub mod ata;