From 6a41b4aff55d07488a331a56ad0d75138e4ddc12 Mon Sep 17 00:00:00 2001
From: Nicholas Bishop <nbishop@nbishop.net>
Date: Sun, 16 Mar 2025 00:02:20 -0400
Subject: [PATCH] Update Protocol/unsafe_protocol docstrings

---
 uefi-macros/src/lib.rs | 12 ++++++------
 uefi/src/proto/mod.rs  | 14 +++++++++++---
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/uefi-macros/src/lib.rs b/uefi-macros/src/lib.rs
index eaf329dad..94bb01f0d 100644
--- a/uefi-macros/src/lib.rs
+++ b/uefi-macros/src/lib.rs
@@ -25,12 +25,12 @@ macro_rules! err {
 
 /// Attribute macro for marking structs as UEFI protocols.
 ///
-/// The macro takes one argument, either a GUID string or the path to a `Guid`
-/// constant.
+/// The macro can only be applied to a struct, and takes one argument, either a
+/// GUID string or the path to a `Guid` constant.
 ///
-/// The macro can only be applied to a struct. It implements the
-/// [`Protocol`] trait and the `unsafe` [`Identify`] trait for the
-/// struct.
+/// The macro implements the [`Protocol`] trait and the `unsafe` [`Identify`]
+/// trait for the struct. See the [`Protocol`] trait for details of how it is
+/// used.
 ///
 /// # Safety
 ///
@@ -55,7 +55,7 @@ macro_rules! err {
 /// assert_eq!(ExampleProtocol2::GUID, PROTO_GUID);
 /// ```
 ///
-/// [`Identify`]: https://docs.rs/uefi/latest/uefi/trait.Identify.html
+/// [`Identify`]: https://docs.rs/uefi/latest/uefi/data_types/trait.Identify.html
 /// [`Protocol`]: https://docs.rs/uefi/latest/uefi/proto/trait.Protocol.html
 /// [send-and-sync]: https://doc.rust-lang.org/nomicon/send-and-sync.html
 #[proc_macro_attribute]
diff --git a/uefi/src/proto/mod.rs b/uefi/src/proto/mod.rs
index dd749da51..e77f856a0 100644
--- a/uefi/src/proto/mod.rs
+++ b/uefi/src/proto/mod.rs
@@ -34,10 +34,18 @@ pub use uefi_macros::unsafe_protocol;
 use crate::Identify;
 use core::ffi::c_void;
 
-/// Common trait implemented by all standard UEFI protocols.
+#[cfg(doc)]
+use crate::boot;
+
+/// Marker trait for structures that represent UEFI protocols.
+///
+/// Implementing this trait allows a protocol to be opened with
+/// [`boot::open_protocol`] or [`boot::open_protocol_exclusive`]. Note that
+/// implementing this trait does not automatically install a protocol. To
+/// install a protocol, call [`boot::install_protocol_interface`].
 ///
-/// You can derive the `Protocol` trait and specify the protocol's GUID using
-/// the [`unsafe_protocol`] macro.
+/// As a convenience, you can derive the `Protocol` trait and specify the
+/// protocol's GUID using the [`unsafe_protocol`] macro.
 ///
 /// # Example
 ///