Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit ac57827

Browse files
committed
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.
1 parent 32d121a commit ac57827

File tree

29 files changed

+129
-34
lines changed

29 files changed

+129
-34
lines changed

‎uefi-raw/src/protocol/device_path.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
//!
88
//! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
99
//! An open UEFI device path [protocol], also called _device path_, is a
10-
//! flexible and structured sequence of binary nodes that describe a route from
10+
//! flexible and structured sequence of binary nodes that describes a route from
1111
//! the UEFI root to a particular device, controller, or file.
1212
//!
1313
//! An entire device path can be made up of multiple device path instances,

‎uefi/src/proto/console/gop.rs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,10 +65,13 @@ use uefi_raw::protocol::console::{
6565

6666
pub use uefi_raw::protocol::console::PixelBitmask;
6767

68-
/// Provides access to the video hardware's frame buffer.
68+
/// Graphics Output [`Protocol`] (GOP). Provides access to the video hardware's
69+
/// frame buffer.
6970
///
70-
/// The GOP can be used to set the properties of the frame buffer,
71-
/// and also allows the app to access the in-memory buffer.
71+
/// The GOP can be used to set the properties of the framebuffer, and also
72+
/// allows the app to access the in-memory buffer.
73+
///
74+
/// [`Protocol`]: uefi::proto::Protocol
7275
#[derive(Debug)]
7376
#[repr(transparent)]
7477
#[unsafe_protocol(GraphicsOutputProtocol::GUID)]

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,11 @@ use crate::proto::unsafe_protocol;
66
use crate::{Event, Result, Status, StatusExt};
77
use uefi_raw::protocol::console::SimplePointerProtocol;
88

9-
/// Provides information about a pointer device.
9+
/// Simple Pointer [`Protocol`]. Provides information about a pointer device.
10+
///
11+
/// Pointer devices are mouses, touchpads, and touchscreens.
12+
///
13+
/// [`Protocol`]: uefi::proto::Protocol
1014
#[derive(Debug)]
1115
#[repr(transparent)]
1216
#[unsafe_protocol(SimplePointerProtocol::GUID)]

‎uefi/src/proto/console/serial.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,15 @@ pub use uefi_raw::protocol::console::serial::{
1111
ControlBits, Parity, SerialIoMode as IoMode, StopBits,
1212
};
1313

14-
/// Provides access to a serial I/O device.
14+
/// Serial IO [`Protocol`]. Provides access to a serial I/O device.
1515
///
1616
/// This can include standard UART devices, serial ports over a USB interface,
1717
/// or any other character-based communication device.
1818
///
1919
/// Since UEFI drivers are implemented through polling, if you fail to regularly
2020
/// check for input/output, some data might be lost.
21+
///
22+
/// [`Protocol`]: uefi::proto::Protocol
2123
#[derive(Debug)]
2224
#[repr(transparent)]
2325
#[unsafe_protocol(SerialIoProtocol::GUID)]

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,9 @@ use crate::{Char16, Event, Result, Status, StatusExt};
55
use core::mem::MaybeUninit;
66
use uefi_raw::protocol::console::{InputKey, SimpleTextInputProtocol};
77

8-
/// Interface for text-based input devices.
8+
/// Simple Text Input [`Protocol`]. Interface for text-based input devices.
9+
///
10+
/// [`Protocol`]: uefi::proto::Protocol
911
#[derive(Debug)]
1012
#[repr(transparent)]
1113
#[unsafe_protocol(SimpleTextInputProtocol::GUID)]

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ use crate::{CStr16, Result, ResultExt, Status, StatusExt};
55
use core::fmt;
66
use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol};
77

8-
/// Interface for text-based output devices.
8+
/// Simple Text Output [`Protocol`]. Interface for text-based output devices.
99
///
1010
/// It implements the fmt::Write trait, so you can use it to print text with
1111
/// standard Rust constructs like the `write!()` and `writeln!()` macros.
@@ -22,6 +22,7 @@ use uefi_raw::protocol::console::{SimpleTextOutputMode, SimpleTextOutputProtocol
2222
/// [`system::stdout`]: crate::system::with_stdout
2323
/// [`system::stderr`]: crate::system::with_stderr
2424
/// [`boot`]: crate::boot#accessing-protocols
25+
/// [`Protocol`]: uefi::proto::Protocol
2526
#[derive(Debug)]
2627
#[repr(transparent)]
2728
#[unsafe_protocol(SimpleTextOutputProtocol::GUID)]

‎uefi/src/proto/debug/mod.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ pub use exception::ExceptionType;
2323
mod context;
2424
mod exception;
2525

26+
/// Debug support [`Protocol`].
27+
///
2628
/// The debugging support protocol allows debuggers to connect to a UEFI machine.
2729
/// It is expected that there will typically be two instances of the EFI Debug Support protocol in the system.
2830
/// One associated with the native processor instruction set (IA-32, x64, ARM, RISC-V, or Itanium processor
@@ -31,6 +33,8 @@ mod exception;
3133
/// one for any given instruction set.
3234
///
3335
/// NOTE: OVMF only implements this protocol interface for the virtual EBC processor
36+
///
37+
/// [`Protocol`]: uefi::proto::Protocol
3438
#[derive(Debug)]
3539
#[repr(C)]
3640
#[unsafe_protocol("2755590c-6f3c-42fa-9ea4-a3ba543cda25")]
@@ -178,8 +182,12 @@ pub enum ProcessorArch: u32 => {
178182
RISCV_128 = 0x5128,
179183
}}
180184

185+
/// Debug Port [`Protocol`].
186+
///
181187
/// The debug port protocol abstracts the underlying debug port
182188
/// hardware, whether it is a regular Serial port or something else.
189+
///
190+
/// [`Protocol`]: uefi::proto::Protocol
183191
#[derive(Debug)]
184192
#[repr(C)]
185193
#[unsafe_protocol("eba4e8d2-3858-41ec-a281-2647ba9660d0")]

‎uefi/src/proto/device_path/mod.rs‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
//!
99
//! # Terminology: Device Paths, Device Path Instances, and Device Path Nodes
1010
//! An open UEFI device path [`Protocol`], also called _device path_, is a
11-
//! flexible and structured sequence of binary nodes that describe a route from
11+
//! flexible and structured sequence of binary nodes that describes a route from
1212
//! the UEFI root to a particular device, controller, or file.
1313
//!
1414
//! An entire device path can be made up of multiple device path instances,
@@ -768,12 +768,15 @@ pub enum NodeConversionError {
768768
UnsupportedType,
769769
}
770770

771+
/// Loaded Image Device Path [`Protocol`].
772+
///
771773
/// Protocol for accessing the device path that was passed in to [`load_image`]
772774
/// when loading a PE/COFF image.
773775
///
774776
/// The layout of this type is the same as a [`DevicePath`].
775777
///
776778
/// [`load_image`]: crate::boot::load_image
779+
/// [`Protocol`]: uefi::proto::Protocol
777780
#[repr(transparent)]
778781
#[unsafe_protocol("bc62157e-3e33-4fec-9920-2d3b36d750df")]
779782
#[derive(Debug, Pointee)]

‎uefi/src/proto/device_path/text.rs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,11 @@ pub struct DisplayOnly(pub bool);
4747
#[derive(Clone, Copy, Debug)]
4848
pub struct AllowShortcuts(pub bool);
4949

50+
/// Device Path to Text [`Protocol`].
51+
///
5052
/// Protocol for converting a [`DevicePath`] or `DevicePathNode`] to a string.
53+
///
54+
/// [`Protocol`]: uefi::proto::Protocol
5155
#[derive(Debug)]
5256
#[repr(transparent)]
5357
#[unsafe_protocol(DevicePathToTextProtocol::GUID)]
@@ -99,7 +103,11 @@ impl DevicePathToText {
99103
}
100104
}
101105

106+
/// Device Path from Text [`Protocol`].
107+
///
102108
/// Protocol for converting a string to a [`DevicePath`] or `DevicePathNode`].
109+
///
110+
/// [`Protocol`]: uefi::proto::Protocol
103111
#[derive(Debug)]
104112
#[repr(transparent)]
105113
#[unsafe_protocol("05c99a21-c70f-4ad2-8a5f-35df3343f51e")]

‎uefi/src/proto/driver/component_name.rs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ use core::fmt::{self, Debug, Display, Formatter};
1313
use core::{ptr, slice};
1414
use uefi_raw::protocol::driver::ComponentName2Protocol;
1515

16+
/// Component Name1 [`Protocol`].
17+
///
1618
/// Protocol that provides human-readable names for a driver and for each of the
1719
/// controllers that the driver is managing.
1820
///
@@ -27,6 +29,7 @@ use uefi_raw::protocol::driver::ComponentName2Protocol;
2729
///
2830
/// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
2931
/// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
32+
/// [`Protocol`]: uefi::proto::Protocol
3033
#[deprecated = "deprecated in UEFI 2.1; use ComponentName2 where possible"]
3134
#[unsafe_protocol(ComponentName2Protocol::DEPRECATED_COMPONENT_NAME_GUID)]
3235
#[derive(Debug)]
@@ -87,6 +90,8 @@ impl ComponentName1 {
8790
}
8891
}
8992

93+
/// Component Name2 [`Protocol`].
94+
///
9095
/// Protocol that provides human-readable names for a driver and for each of the
9196
/// controllers that the driver is managing.
9297
///
@@ -101,6 +106,7 @@ impl ComponentName1 {
101106
///
102107
/// [ISO 639-2]: https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes
103108
/// [RFC 4646]: https://www.rfc-editor.org/rfc/rfc4646
109+
/// [`Protocol`]: uefi::proto::Protocol
104110
#[unsafe_protocol(ComponentName2Protocol::GUID)]
105111
#[derive(Debug)]
106112
#[repr(transparent)]

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /