uefi: streamline documentation of Protocol structs

Now each struct's documentation begins with "$ProtocolName [`Protocol`]". This
way, readers quickly can figure out what Protocols are in general.

Author: phip1611

uefi/src/proto/console/gop.rs

@@ -65,10 +65,13 @@ use uefi_raw::protocol::console::{
 
 pub use uefi_raw::protocol::console::PixelBitmask;
 
-/// Provides access to the video hardware's frame buffer.
+/// Graphics Output [`Protocol`] (GOP). Provides access to the video hardware's
+/// frame buffer.
 ///
-/// The GOP can be used to set the properties of the frame buffer,
-/// and also allows the app to access the in-memory buffer.
+/// The GOP can be used to set the properties of the framebuffer, and also
+/// allows the app to access the in-memory buffer.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(GraphicsOutputProtocol::GUID)]

uefi/src/proto/console/pointer/mod.rs

@@ -6,7 +6,11 @@ use crate::proto::unsafe_protocol;
 use crate::{Event, Result, Status, StatusExt};
 use uefi_raw::protocol::console::SimplePointerProtocol;
 
-/// Provides information about a pointer device.
+/// Simple Pointer [`Protocol`]. Provides information about a pointer device.
+///
+/// Pointer devices are mouses, touchpads, and touchscreens.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimplePointerProtocol::GUID)]

uefi/src/proto/console/serial.rs

@@ -11,13 +11,15 @@ pub use uefi_raw::protocol::console::serial::{
     ControlBits, Parity, SerialIoMode as IoMode, StopBits,
 };
 
-/// Provides access to a serial I/O device.
+/// Serial IO [`Protocol`]. Provides access to a serial I/O device.
 ///
 /// This can include standard UART devices, serial ports over a USB interface,
 /// or any other character-based communication device.
 ///
 /// Since UEFI drivers are implemented through polling, if you fail to regularly
 /// check for input/output, some data might be lost.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SerialIoProtocol::GUID)]

uefi/src/proto/console/text/input.rs

@@ -5,7 +5,9 @@ use crate::{Char16, Event, Result, Status, StatusExt};
 use core::mem::MaybeUninit;
 use uefi_raw::protocol::console::{InputKey, SimpleTextInputProtocol};
 
-/// Interface for text-based input devices.
+/// Simple Text Input [`Protocol`]. Interface for text-based input devices.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleTextInputProtocol::GUID)]

uefi/src/proto/console/text/output.rs

@@ -5,7 +5,7 @@ use crate::{CStr16, Result, ResultExt, Status, StatusExt};
 use core::fmt;
 use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol};
 
-/// Interface for text-based output devices.
+/// Simple Text Output [`Protocol`]. Interface for text-based output devices.
 ///
 /// It implements the fmt::Write trait, so you can use it to print text with
 /// standard Rust constructs like the `write!()` and `writeln!()` macros.
@@ -22,6 +22,7 @@ use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol
 /// [`system::stdout`]: crate::system::with_stdout
 /// [`system::stderr`]: crate::system::with_stderr
 /// [`boot`]: crate::boot#accessing-protocols
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleTextOutputProtocol::GUID)]

uefi/src/proto/debug/mod.rs

@@ -23,6 +23,8 @@ pub use exception::ExceptionType;
 mod context;
 mod exception;
 
+/// Debug support [`Protocol`].
+///
 /// The debugging support protocol allows debuggers to connect to a UEFI machine.
 /// It is expected that there will typically be two instances of the EFI Debug Support protocol in the system.
 /// One associated with the native processor instruction set (IA-32, x64, ARM, RISC-V, or Itanium processor
@@ -31,6 +33,8 @@ mod exception;
 /// one for any given instruction set.
 ///
 /// NOTE: OVMF only implements this protocol interface for the virtual EBC processor
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
@@ -178,8 +182,12 @@ pub enum ProcessorArch: u32 => {
     RISCV_128   = 0x5128,
 }}
 
+/// Debug Port [`Protocol`].
+///
 /// The debug port protocol abstracts the underlying debug port
 /// hardware, whether it is a regular Serial port or something else.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(C)]
 #[unsafe_protocol("eba4e8d2-3858-41ec-a281-2647ba9660d0")]

uefi/src/proto/device_path/mod.rs

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Device Path protocol
+//! Helpers to work with UEFI Device Paths and the Device Path Protocol.
 //!
-//! A UEFI device path is a very flexible structure for encoding a
-//! programmatic path such as a hard drive or console.
+//! 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,7 +345,7 @@ impl ToOwned for DevicePathInstance {
     }
 }
 
-/// Device path protocol.
+/// Device Path [`Protocol`].
 ///
 /// 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
@@ -359,6 +358,7 @@ impl ToOwned for DevicePathInstance {
 ///
 /// [module-level documentation]: crate::proto::device_path
 /// [`END_ENTIRE`]: DeviceSubType::END_ENTIRE
+/// [`Protocol`]: uefi::proto::Protocol
 #[repr(C, packed)]
 #[unsafe_protocol(uefi_raw::protocol::device_path::DevicePathProtocol::GUID)]
 #[derive(Eq, Pointee)]
@@ -656,12 +656,15 @@ pub enum NodeConversionError {
     UnsupportedType,
 }
 
+/// Loaded Image Device Path [`Protocol`].
+///
 /// Protocol for accessing the device path that was passed in to [`load_image`]
 /// when loading a PE/COFF image.
 ///
 /// The layout of this type is the same as a [`DevicePath`].
 ///
 /// [`load_image`]: crate::boot::load_image
+/// [`Protocol`]: uefi::proto::Protocol
 #[repr(transparent)]
 #[unsafe_protocol("bc62157e-3e33-4fec-9920-2d3b36d750df")]
 #[derive(Debug, Pointee)]

uefi/src/proto/device_path/text.rs

@@ -94,7 +94,11 @@ impl Deref for PoolDevicePathNode {
     }
 }
 
+/// Device Path to Text [`Protocol`].
+///
 /// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DevicePathToTextProtocol::GUID)]
@@ -146,7 +150,11 @@ impl DevicePathToText {
     }
 }
 
+/// Device Path from Text [`Protocol`].
+///
 /// Protocol for converting a string to a [`DevicePath`] or `DevicePathNode`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol("05c99a21-c70f-4ad2-8a5f-35df3343f51e")]

uefi/src/proto/driver/component_name.rs

@@ -13,6 +13,8 @@ use core::fmt::{self, Debug, Display, Formatter};
 use core::{ptr, slice};
 use uefi_raw::protocol::driver::ComponentName2Protocol;
 
+/// Component Name1 [`Protocol`].
+///
 /// Protocol that provides human-readable names for a driver and for each of the
 /// controllers that the driver is managing.
 ///
@@ -27,6 +29,7 @@ use uefi_raw::protocol::driver::ComponentName2Protocol;
 ///
 /// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
 /// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
+/// [`Protocol`]: uefi::proto::Protocol
 #[deprecated = "deprecated in UEFI 2.1; use ComponentName2 where possible"]
 #[unsafe_protocol(ComponentName2Protocol::DEPRECATED_COMPONENT_NAME_GUID)]
 #[derive(Debug)]
@@ -85,6 +88,8 @@ impl ComponentName1 {
     }
 }
 
+/// Component Name2 [`Protocol`].
+///
 /// Protocol that provides human-readable names for a driver and for each of the
 /// controllers that the driver is managing.
 ///
@@ -99,6 +104,7 @@ impl ComponentName1 {
 ///
 /// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
 /// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
+/// [`Protocol`]: uefi::proto::Protocol
 #[unsafe_protocol(ComponentName2Protocol::GUID)]
 #[derive(Debug)]
 #[repr(transparent)]

uefi/src/proto/loaded_image.rs

@@ -12,7 +12,12 @@ use core::ffi::c_void;
 use core::{mem, slice};
 use uefi_raw::protocol::loaded_image::LoadedImageProtocol;
 
-/// The LoadedImage protocol. This can be opened on any image handle using the `HandleProtocol` boot service.
+/// The Loaded Image [`Protocol`].
+///
+/// This can be opened on any image handle using [`boot::open_protocol`],
+/// for example.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadedImageProtocol::GUID)]

uefi/src/proto/media/block.rs

@@ -7,7 +7,9 @@ use crate::{Result, StatusExt};
 
 pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
 
-/// The Block I/O protocol.
+/// Block I/O [`Protocol`].
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(BlockIoProtocol::GUID)]

uefi/src/proto/media/disk.rs

@@ -1,19 +1,21 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
-//! Disk I/O protocols.
+//! Disk I/O protocols [`DiskIo`] and [`DiskIo2`].
 
 use crate::proto::unsafe_protocol;
 use crate::util::opt_nonnull_to_ptr;
 use crate::{Event, Result, Status, StatusExt};
 use core::ptr::NonNull;
 use uefi_raw::protocol::disk::{DiskIo2Protocol, DiskIoProtocol};
 
-/// The disk I/O protocol.
+/// Disk I/O [`Protocol`].
 ///
 /// This protocol is used to abstract the block accesses of the block I/O
 /// protocol to a more general offset-length protocol. Firmware is
 /// responsible for adding this protocol to any block I/O interface that
 /// appears in the system that does not already have a disk I/O protocol.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskIoProtocol::GUID)]
@@ -82,10 +84,12 @@ pub struct DiskIo2Token {
     pub transaction_status: Status,
 }
 
-/// The disk I/O 2 protocol.
+/// Disk I/O 2 [`Protocol`].
 ///
 /// This protocol provides an extension to the disk I/O protocol to enable
 /// non-blocking / asynchronous byte-oriented disk operation.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskIo2Protocol::GUID)]

uefi/src/proto/media/disk_info.rs

@@ -52,7 +52,7 @@ pub struct DeviceLocationInfo {
     pub device: u32,
 }
 
-/// DiskInfo protocol.
+/// Disk Info [`Protocol`].
 ///
 /// This allows querying hardware information for detected disks in a simple way.
 /// Originally, this was designed for IDE and it shows.
@@ -64,6 +64,8 @@ pub struct DeviceLocationInfo {
 ///
 /// # UEFI Spec Description
 /// Provides the basic interfaces to abstract platform information regarding an IDE controller.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(DiskInfoProtocol::GUID)]

uefi/src/proto/media/fs.rs

@@ -8,7 +8,8 @@ use crate::{Result, StatusExt};
 use core::ptr;
 use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
 
-/// Allows access to a FAT-12/16/32 file system.
+/// Simple File System [`Protocol`]. Allows access to a FAT-12/16/32 file
+/// system.
 ///
 /// This interface is implemented by some storage devices
 /// to allow file access to the contained file systems.
@@ -22,6 +23,7 @@ use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
 ///
 /// [`boot::get_image_file_system`]: crate::boot::get_image_file_system
 /// [`boot`]: crate::boot#accessing-protocols
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(SimpleFileSystemProtocol::GUID)]

uefi/src/proto/media/load_file.rs

@@ -16,7 +16,7 @@ use {
     uefi_raw::Boolean,
 };
 
-/// Load File Protocol.
+/// Load File [`Protocol`].
 ///
 /// Used to obtain files, that are primarily boot options, from arbitrary
 /// devices.
@@ -33,6 +33,8 @@ use {
 /// EFI_LOAD_FILE_PROTOCOL and the LoadFile() function. In this case the
 /// LoadFile() function implements the policy of interpreting the File Path
 /// value.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadFileProtocol::GUID)]
@@ -98,7 +100,7 @@ impl LoadFile {
     }
 }
 
-/// Load File2 Protocol.
+/// Load File2 [`Protocol`].
 ///
 /// The Load File2 protocol is used to obtain files from arbitrary devices that
 /// are not boot options.
@@ -109,6 +111,8 @@ impl LoadFile {
 /// arbitrary devices that are not boot options. It is used by LoadImage() when
 /// its BootOption parameter is FALSE and the FilePath does not have an instance
 /// of the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(LoadFile2Protocol::GUID)]

uefi/src/proto/media/partition.rs

@@ -221,7 +221,11 @@ newtype_enum! {
     }
 }
 
+/// Partition Info [`Protocol`].
+///
 /// Protocol for accessing partition information.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[allow(missing_debug_implementations)]
 #[repr(C)]
 #[repr(packed)]

uefi/src/proto/misc.rs

@@ -9,10 +9,17 @@ use uefi_raw::protocol::misc::{
 use crate::proto::unsafe_protocol;
 use crate::{Result, StatusExt};
 
+/// Timestamp [`Protocol`].
+///
 /// Protocol for retrieving a high-resolution timestamp counter.
-/// **Note:**
-/// If your UEFI firmware not support timestamp protocol which first added at UEFI spec 2.4 2013.
-/// you also could use `RDTSC` in rust, here is a demo [Slint-UI](https://github.com/slint-ui/slint/blob/2c0ba2bc0f151eba8d1fa17839fa2ac58832ca80/examples/uefi-demo/main.rs#L28-L62) who use uefi-rs.
+///
+/// # Note
+/// If your UEFI firmware not support timestamp protocol which first added at
+/// UEFI spec 2.4 2013. you also could use `RDTSC` in rust, here is a demo
+/// [Slint-UI](https://github.com/slint-ui/slint/blob/2c0ba2bc0f151eba8d1fa17839fa2ac58832ca80/examples/uefi-demo/main.rs#L28-L62)
+/// who use uefi-rs.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(TimestampProtocol::GUID)]
@@ -32,7 +39,11 @@ impl Timestamp {
     }
 }
 
+/// Reset Notification [`Protocol`].
+///
 /// Protocol to register for a notification when ResetSystem is called.
+///
+/// [`Protocol`]: uefi::proto::Protocol
 #[derive(Debug)]
 #[repr(transparent)]
 #[unsafe_protocol(ResetNotificationProtocol::GUID)]