Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 8bbbe4f

Browse files
committedApr 5, 2025·
doc: streamline
Streamline all `# Errors` and `# Arguments` sections. This is about the style, not the content. The advantage of this streamlined and consistent style, is that new contributions can follow the guideline. This however is only a partial solution, in case we ever want to have a 100% streamlined documentation across the whole crate. No major changes have been made with a few small exceptions, where I deleted obviously wrong or irrelevant error codes.
1 parent 14ef880 commit 8bbbe4f

File tree

18 files changed

+345
-367
lines changed

18 files changed

+345
-367
lines changed
 

‎uefi/src/boot.rs

Lines changed: 82 additions & 107 deletions
Large diffs are not rendered by default.

‎uefi/src/data_types/strs.rs

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -362,7 +362,6 @@ impl CStr16 {
362362
/// Creates a `&CStr16` from a u16 slice, stopping at the first nul character.
363363
///
364364
/// # Errors
365-
///
366365
/// An error is returned if the slice contains invalid UCS-2 characters, or
367366
/// if the slice does not contain any nul character.
368367
pub fn from_u16_until_nul(codes: &[u16]) -> Result<&Self, FromSliceUntilNulError> {
@@ -411,7 +410,6 @@ impl CStr16 {
411410
/// Creates a `&CStr16` from a [`Char16`] slice, stopping at the first nul character.
412411
///
413412
/// # Errors
414-
///
415413
/// An error is returned if the slice does not contain any nul character.
416414
pub fn from_char16_until_nul(chars: &[Char16]) -> Result<&Self, FromSliceUntilNulError> {
417415
// Find the index of the first null char.

‎uefi/src/mem/memory_map/impl_.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -275,7 +275,7 @@ pub(crate) struct MemoryMapBackingMemory(NonNull<[u8]>);
275275
impl MemoryMapBackingMemory {
276276
/// Constructs a new [`MemoryMapBackingMemory`].
277277
///
278-
/// # Parameters
278+
/// # Arguments
279279
/// - `memory_type`: The memory type for the memory map allocation.
280280
/// Typically, [`MemoryType::LOADER_DATA`] for regular UEFI applications.
281281
pub(crate) fn new(memory_type: MemoryType) -> crate::Result<Self> {

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

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@ impl Pointer {
1616
/// Resets the pointer device hardware.
1717
///
1818
/// # Arguments
19-
/// The `extended_verification` parameter is used to request that UEFI
20-
/// performs an extended check and reset of the input device.
19+
/// - `extended_verification`: Request that UEFI performs an extended check
20+
/// and reset of the input device.
2121
///
2222
/// # Errors
23-
/// - `DeviceError` if the device is malfunctioning and cannot be reset.
23+
/// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot be
24+
/// reset.
2425
pub fn reset(&mut self, extended_verification: bool) -> Result {
2526
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
2627
}

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

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,13 @@ pub struct Input(SimpleTextInputProtocol);
1414
impl Input {
1515
/// Resets the input device hardware.
1616
///
17-
/// The `extended_verification` parameter is used to request that UEFI
18-
/// performs an extended check and reset of the input device.
17+
/// # Arguments
18+
/// - `extended_verification`: Request that UEFI performs an extended check
19+
/// and reset of the input device.
1920
///
2021
/// # Errors
21-
///
22-
/// - `DeviceError` if the device is malfunctioning and cannot be reset.
22+
/// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot
23+
/// be reset.
2324
pub fn reset(&mut self, extended_verification: bool) -> Result {
2425
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
2526
}
@@ -33,7 +34,6 @@ impl Input {
3334
/// [`wait_for_key_event`]: Self::wait_for_key_event
3435
///
3536
/// # Errors
36-
///
3737
/// - [`Status::DEVICE_ERROR`] if there was an issue with the input device
3838
///
3939
/// # Examples

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -401,7 +401,6 @@ impl DevicePath {
401401
/// end-entire node.
402402
///
403403
/// # Errors
404-
///
405404
/// The [`ByteConversionError::InvalidLength`] error will be returned
406405
/// when the length of the given bytes slice cannot contain the full
407406
/// [`DevicePath`] represented by the slice.

‎uefi/src/proto/media/block.rs

Lines changed: 30 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
//! Block I/O protocols.
44
55
use crate::proto::unsafe_protocol;
6+
#[cfg(doc)]
7+
use crate::Status;
68
use crate::{Result, StatusExt};
79

810
pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
@@ -23,11 +25,11 @@ impl BlockIO {
2325
/// Resets the block device hardware.
2426
///
2527
/// # Arguments
26-
/// * `extended_verification` Indicates that the driver may perform a more
27-
/// exhaustive verification operation of the device during reset.
28+
/// * `extended_verification`: Request that UEFI performs an extended check
29+
/// and reset of the input device.
2830
///
2931
/// # Errors
30-
/// * `uefi::Status::DEVICE_ERROR` The block device is not functioning
32+
/// * [`Status::DEVICE_ERROR`] if the block device is not functioning
3133
/// correctly and could not be reset.
3234
pub fn reset(&mut self, extended_verification: bool) -> Result {
3335
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
@@ -36,18 +38,20 @@ impl BlockIO {
3638
/// Read the requested number of blocks from the device.
3739
///
3840
/// # Arguments
39-
/// * `media_id` - The media ID that the read request is for.
40-
/// * `lba` - The starting logical block address to read from on the device.
41-
/// * `buffer` - The target buffer of the read operation
41+
/// * `media_id`: The media ID that the read request is for.
42+
/// * `lba`: The starting logical block address to read from on the device.
43+
/// * `buffer`: The target buffer of the read operation
4244
///
4345
/// # Errors
44-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error while attempting to perform the read
45-
/// operation.
46-
/// * `uefi::Status::NO_MEDIA` There is no media in the device.
47-
/// * `uefi::Status::MEDIA_CHANGED` The `media_id` is not for the current media.
48-
/// * `uefi::Status::BAD_BUFFER_SIZE` The buffer size parameter is not a multiple of the intrinsic block size of
49-
/// the device.
50-
/// * `uefi::Status::INVALID_PARAMETER` The read request contains LBAs that are not valid, or the buffer is not on
46+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
47+
/// attempting to perform the read operation.
48+
/// * [`Status::NO_MEDIA`] when there is no media in the device.
49+
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
50+
/// media.
51+
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
52+
/// a multiple of the intrinsic block size of the device.
53+
/// * [`Status::INVALID_PARAMETER`] when the read request contains LBAs
54+
/// that are not valid, or the buffer is not on
5155
/// proper alignment.
5256
pub fn read_blocks(&self, media_id: u32, lba: Lba, buffer: &mut [u8]) -> Result {
5357
let buffer_size = buffer.len();
@@ -66,20 +70,21 @@ impl BlockIO {
6670
/// Writes the requested number of blocks to the device.
6771
///
6872
/// # Arguments
69-
/// * `media_id` The media ID that the write request is for.
70-
/// * `lba` The starting logical block address to be written.
71-
/// * `buffer` Buffer to be written
73+
/// * `media_id`: The media ID that the write request is for.
74+
/// * `lba`: The starting logical block address to be written.
75+
/// * `buffer`: Buffer to be written
7276
///
7377
/// # Errors
74-
/// * `uefi::Status::WRITE_PROTECTED` The device cannot be written to.
75-
/// * `uefi::Status::NO_MEDIA` There is no media in the device.
76-
/// * `uefi::Status::MEDIA_CHANGED` The `media_id` is not for the current media.
77-
/// * `uefi::Status::DEVICE_ERROR` The device reported an error while attempting to perform the write
78-
/// operation.
79-
/// * `uefi::Status::BAD_BUFFER_SIZE` The buffer size parameter is not a multiple of the intrinsic block size
80-
/// of the device.
81-
/// * `uefi::Status::INVALID_PARAMETER` The write request contains LBAs that are not valid, or the buffer is not
82-
/// on proper alignment.
78+
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
79+
/// * [`Status::NO_MEDIA`] when there is no media in the device.
80+
/// * [`Status::MEDIA_CHANGED`] when the `media_id` is not for the
81+
/// current media.
82+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
83+
/// attempting to perform the write operation.
84+
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
85+
/// a multiple of the intrinsic block size of the device.
86+
/// * [`Status::INVALID_PARAMETER`] The write request contains LBAs that
87+
/// are not valid, or the buffer is not on proper alignment.
8388
pub fn write_blocks(&mut self, media_id: u32, lba: Lba, buffer: &[u8]) -> Result {
8489
let buffer_size = buffer.len();
8590
unsafe {

‎uefi/src/proto/media/disk.rs

Lines changed: 70 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -22,16 +22,19 @@ pub struct DiskIo(DiskIoProtocol);
2222
impl DiskIo {
2323
/// Reads bytes from the disk device.
2424
///
25-
/// # Arguments:
26-
/// * `media_id` - ID of the medium to be read.
27-
/// * `offset` - Starting byte offset on the logical block I/O device to read from.
28-
/// * `buffer` - Pointer to a buffer to read into.
25+
/// # Arguments
26+
/// * `media_id`: ID of the medium to be read.
27+
/// * `offset`: Starting byte offset on the logical block I/O device to read from.
28+
/// * `buffer`: Pointer to a buffer to read into.
2929
///
30-
/// # Errors:
31-
/// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
32-
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation.
33-
/// * [`Status::NO_MEDIA`] There is no medium in the device.
34-
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
30+
/// # Errors
31+
/// * [`Status::INVALID_PARAMETER`] when the read request contains device
32+
/// addresses that are not valid for the device.
33+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
34+
/// performing the read operation.
35+
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
36+
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
37+
/// medium.
3538
pub fn read_disk(&self, media_id: u32, offset: u64, buffer: &mut [u8]) -> Result {
3639
unsafe {
3740
(self.0.read_disk)(
@@ -47,17 +50,20 @@ impl DiskIo {
4750

4851
/// Writes bytes to the disk device.
4952
///
50-
/// # Arguments:
51-
/// * `media_id` - ID of the medium to be written.
52-
/// * `offset` - Starting byte offset on the logical block I/O device to write to.
53-
/// * `buffer` - Pointer to a buffer to write from.
53+
/// # Arguments
54+
/// * `media_id`: ID of the medium to be written.
55+
/// * `offset`: Starting byte offset on the logical block I/O device to write to.
56+
/// * `buffer`: Pointer to a buffer to write from.
5457
///
55-
/// # Errors:
56-
/// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
57-
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation.
58-
/// * [`Status::NO_MEDIA`] There is no medium in the device.
59-
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
60-
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
58+
/// # Errors
59+
/// * [`Status::INVALID_PARAMETER`] when the write request contains device
60+
/// addresses that are not valid for the device.
61+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
62+
/// performing the write operation.
63+
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
64+
/// * [`Status::MEDIA_CHANGED`] then `media_id` is not for the current
65+
/// medium.
66+
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
6167
pub fn write_disk(&mut self, media_id: u32, offset: u64, buffer: &[u8]) -> Result {
6268
unsafe {
6369
(self.0.write_disk)(
@@ -94,32 +100,36 @@ pub struct DiskIo2(DiskIo2Protocol);
94100
impl DiskIo2 {
95101
/// Terminates outstanding asynchronous requests to the device.
96102
///
97-
/// # Errors:
103+
/// # Errors
98104
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing
99105
pub fn cancel(&mut self) -> Result {
100106
unsafe { (self.0.cancel)(&mut self.0) }.to_result()
101107
}
102108

103109
/// Reads bytes from the disk device.
104110
///
105-
/// # Arguments:
106-
/// * `media_id` - ID of the medium to be read from.
107-
/// * `offset` - Starting byte offset on the logical block I/O device to read from.
108-
/// * `token` - Transaction token for asynchronous read.
109-
/// * `len` - Buffer size.
110-
/// * `buffer` - Buffer to read into.
111+
/// # Arguments
112+
/// * `media_id`: ID of the medium to be read from.
113+
/// * `offset`: Starting byte offset on the logical block I/O device to read from.
114+
/// * `token`: Transaction token for asynchronous read.
115+
/// * `len`: Buffer size.
116+
/// * `buffer`: Buffer to read into.
111117
///
112118
/// # Safety
113119
///
114120
/// Because of the asynchronous nature of the disk transaction, manual lifetime
115121
/// tracking is required.
116122
///
117-
/// # Errors:
118-
/// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
119-
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
120-
/// * [`Status::MEDIA_CHANGED`] `media_id` is not for the current medium.
121-
/// * [`Status::NO_MEDIA`] There is no medium in the device.
122-
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the read operation.
123+
/// # Errors
124+
/// * [`Status::INVALID_PARAMETER`] when the read request contains device
125+
/// addresses that are not valid for the device.
126+
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
127+
/// due to a lack of resources.
128+
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
129+
/// medium.
130+
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
131+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
132+
/// performing the read operation.
123133
pub unsafe fn read_disk_raw(
124134
&self,
125135
media_id: u32,
@@ -137,25 +147,29 @@ impl DiskIo2 {
137147

138148
/// Writes bytes to the disk device.
139149
///
140-
/// # Arguments:
141-
/// * `media_id` - ID of the medium to write to.
142-
/// * `offset` - Starting byte offset on the logical block I/O device to write to.
143-
/// * `token` - Transaction token for asynchronous write.
144-
/// * `len` - Buffer size.
145-
/// * `buffer` - Buffer to write from.
150+
/// # Arguments
151+
/// * `media_id`: ID of the medium to write to.
152+
/// * `offset`: Starting byte offset on the logical block I/O device to write to.
153+
/// * `token`: Transaction token for asynchronous write.
154+
/// * `len`: Buffer size.
155+
/// * `buffer`: Buffer to write from.
146156
///
147157
/// # Safety
148158
///
149159
/// Because of the asynchronous nature of the disk transaction, manual lifetime
150160
/// tracking is required.
151161
///
152-
/// # Errors:
153-
/// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
154-
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
155-
/// * [`Status::MEDIA_CHANGED` `media_id` is not for the current medium.
156-
/// * [`Status::NO_MEDIA`] There is no medium in the device.
157-
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the write operation.
158-
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
162+
/// # Errors
163+
/// * [`Status::INVALID_PARAMETER`] when the write request contains device
164+
/// addresses that are not valid for the device.
165+
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
166+
/// due to a lack of resources.
167+
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
168+
/// medium.
169+
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
170+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
171+
/// performing the write operation.
172+
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
159173
pub unsafe fn write_disk_raw(
160174
&mut self,
161175
media_id: u32,
@@ -180,15 +194,18 @@ impl DiskIo2 {
180194

181195
/// Flushes all modified data to the physical device.
182196
///
183-
/// # Arguments:
184-
/// * `token` - Transaction token for the asynchronous flush.
197+
/// # Arguments
198+
/// * `token`: Transaction token for the asynchronous flush.
185199
///
186-
/// # Errors:
187-
/// * [`Status::OUT_OF_RESOURCES`] The request could not be completed due to a lack of resources.
188-
/// * [`Status::MEDIA_CHANGED`] The medium in the device has changed since the last access.
189-
/// * [`Status::NO_MEDIA`] There is no medium in the device.
190-
/// * [`Status::DEVICE_ERROR`] The device reported an error while performing the flush operation.
191-
/// * [`Status::WRITE_PROTECTED`] The device cannot be written to.
200+
/// # Errors
201+
/// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
202+
/// due to a lack of resources.
203+
/// * [`Status::MEDIA_CHANGED`] when the medium in the device has changed
204+
/// since the last access.
205+
/// * [`Status::NO_MEDIA`] when there is no medium in the device.
206+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
207+
/// performing the flush operation.
208+
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
192209
pub fn flush_disk(&mut self, token: Option<NonNull<DiskIo2Token>>) -> Result {
193210
let token = opt_nonnull_to_ptr(token);
194211
unsafe { (self.0.flush_disk_ex)(&mut self.0, token.cast()) }.to_result()

‎uefi/src/proto/media/disk_info.rs

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
//! DiskInfo protocol.
44
5+
#[cfg(doc)]
6+
use crate::Status;
57
use crate::StatusExt;
68
use uefi_macros::unsafe_protocol;
79
use uefi_raw::protocol::disk::DiskInfoProtocol;
@@ -90,17 +92,20 @@ impl DiskInfo {
9092

9193
/// Performs an inquiry command on the disk device.
9294
///
93-
/// # Parameters
95+
/// # Arguments
9496
/// - `bfr`: A mutable byte buffer to store the inquiry data.
9597
///
9698
/// # Returns
9799
/// Length of the response (amount of bytes that were written to the given buffer).
98100
///
99101
/// # Errors
100-
/// - [`crate::Status::SUCCESS`] The command was accepted without any errors.
101-
/// - [`crate::Status::NOT_FOUND`] The device does not support this data class.
102-
/// - [`crate::Status::DEVICE_ERROR`] An error occurred while reading the InquiryData from the device.
103-
/// - [`crate::Status::BUFFER_TOO_SMALL`] The provided InquiryDataSize buffer is not large enough to store the required data.
102+
/// - [`Status::SUCCESS`] when the command was accepted without any errors.
103+
/// - [`Status::NOT_FOUND`] when the device does not support this data
104+
/// class.
105+
/// - [`Status::DEVICE_ERROR`] when an error occurred while reading the
106+
/// inquiry data from the device.
107+
/// - [`Status::BUFFER_TOO_SMALL`] The provided inquiry data size buffer is
108+
/// not large enough to store the required data.
104109
pub fn inquiry(&self, bfr: &mut [u8]) -> crate::Result<usize> {
105110
let mut len: u32 = bfr.len() as u32;
106111
unsafe {
@@ -111,17 +116,20 @@ impl DiskInfo {
111116

112117
/// Performs an identify command on the disk device.
113118
///
114-
/// # Parameters
119+
/// # Arguments
115120
/// - `bfr`: A mutable byte buffer to store the identification data.
116121
///
117122
/// # Returns
118123
/// Length of the response (amount of bytes that were written to the given buffer).
119124
///
120125
/// # Errors
121-
/// - [`crate::Status::SUCCESS`] The command was accepted without any errors.
122-
/// - [`crate::Status::NOT_FOUND`] The device does not support this data class.
123-
/// - [`crate::Status::DEVICE_ERROR`] An error occurred while reading the IdentifyData from the device.
124-
/// - [`crate::Status::BUFFER_TOO_SMALL`] The provided IdentifyDataSize buffer is not large enough to store the required data.
126+
/// - [`Status::SUCCESS`] when the command was accepted without any errors.
127+
/// - [`Status::NOT_FOUND`] when the device does not support this data
128+
/// class.
129+
/// - [`Status::DEVICE_ERROR`] when an error occurred while reading the
130+
/// identify data from the device.
131+
/// - [`Status::BUFFER_TOO_SMALL`] when the provided IdentifyDataSize buffer
132+
/// is not large enough to store the required data.
125133
pub fn identify(&self, bfr: &mut [u8]) -> crate::Result<usize> {
126134
let mut len: u32 = bfr.len() as u32;
127135
unsafe {
@@ -132,17 +140,19 @@ impl DiskInfo {
132140

133141
/// Retrieves sense data from the disk device.
134142
///
135-
/// # Parameters
143+
/// # Arguments
136144
/// - `bfr`: A mutable byte buffer to store the sense data.
137145
///
138146
/// # Returns
139147
/// [`SenseDataInfo`] struct containing the number of bytes of sense data and the number of sense data structures.
140148
///
141149
/// # Errors
142-
/// - [`crate::Status::SUCCESS`] The command was accepted without any errors.
143-
/// - [`crate::Status::NOT_FOUND`] The device does not support this data class.
144-
/// - [`crate::Status::DEVICE_ERROR`] An error occurred while reading the SenseData from the device.
145-
/// - [`crate::Status::BUFFER_TOO_SMALL`] The provided SenseDataSize buffer is not large enough to store the required data.
150+
/// - [`Status::SUCCESS`] when the command was accepted without any errors.
151+
/// - [`Status::NOT_FOUND`] when the device does not support this data class.
152+
/// - [`Status::DEVICE_ERROR`] when an error occurred while reading the
153+
/// sense data from the device.
154+
/// - [`Status::BUFFER_TOO_SMALL`] when the provided sense data buffer is
155+
/// not large enough to store the required data.
146156
pub fn sense_data(&self, bfr: &mut [u8]) -> crate::Result<SenseDataInfo> {
147157
let mut len: u32 = bfr.len() as u32;
148158
let mut number: u8 = 0;
@@ -164,8 +174,8 @@ impl DiskInfo {
164174
/// [`DeviceLocationInfo`] struct containing the channel and device numbers.
165175
///
166176
/// # Errors
167-
/// - [`crate::Status::SUCCESS`] The `IdeChannel` and `IdeDevice` values are valid.
168-
/// - [`crate::Status::UNSUPPORTED`] Not supported by this disk's interface type.
177+
/// - [`Status::SUCCESS`] The `IdeChannel` and `IdeDevice` values are valid.
178+
/// - [`Status::UNSUPPORTED`] Not supported by this disk's interface type.
169179
pub fn bus_location(&self) -> crate::Result<DeviceLocationInfo> {
170180
let mut ide_channel: u32 = 0; // called ide, but also useful for other interfaces
171181
let mut ide_device: u32 = 0;

‎uefi/src/proto/media/file/dir.rs

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,9 @@ impl Directory {
3838
/// alignment through the `Align` trait (`<FileInfo as Align>::alignment()`).
3939
///
4040
/// # Arguments
41-
/// * `buffer` The target buffer of the read operation
41+
/// * `buffer`: The target buffer of the read operation
4242
///
4343
/// # Errors
44-
///
4544
/// All errors come from calls to [`RegularFile::read`].
4645
pub fn read_entry<'buf>(
4746
&mut self,

‎uefi/src/proto/media/file/mod.rs

Lines changed: 35 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -44,29 +44,28 @@ pub trait File: Sized {
4444
/// Try to open a file relative to this file.
4545
///
4646
/// # Arguments
47-
/// * `filename` Path of file to open, relative to this file
48-
/// * `open_mode` The mode to open the file with
49-
/// * `attributes` Only valid when `FILE_MODE_CREATE` is used as a mode
47+
/// * `filename`: Path of file to open, relative to this file
48+
/// * `open_mode`: The mode to open the file with
49+
/// * `attributes`: Only valid when `FILE_MODE_CREATE` is used as a mode
5050
///
5151
/// # Errors
52-
///
5352
/// See section `EFI_FILE_PROTOCOL.Open()` in the UEFI Specification for more details.
5453
/// Note that [`INVALID_PARAMETER`] is not listed in the specification as one of the
5554
/// errors returned by this function, but some implementations (such as EDK2) perform
5655
/// additional validation and may return that status for invalid inputs.
5756
///
58-
/// [`INVALID_PARAMETER`]: uefi::Status::INVALID_PARAMETER
57+
/// [`INVALID_PARAMETER`]: Status::INVALID_PARAMETER
5958
///
60-
/// * [`uefi::Status::INVALID_PARAMETER`]
61-
/// * [`uefi::Status::NOT_FOUND`]
62-
/// * [`uefi::Status::NO_MEDIA`]
63-
/// * [`uefi::Status::MEDIA_CHANGED`]
64-
/// * [`uefi::Status::DEVICE_ERROR`]
65-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
66-
/// * [`uefi::Status::WRITE_PROTECTED`]
67-
/// * [`uefi::Status::ACCESS_DENIED`]
68-
/// * [`uefi::Status::OUT_OF_RESOURCES`]
69-
/// * [`uefi::Status::VOLUME_FULL`]
59+
/// * [`Status::INVALID_PARAMETER`]
60+
/// * [`Status::NOT_FOUND`]
61+
/// * [`Status::NO_MEDIA`]
62+
/// * [`Status::MEDIA_CHANGED`]
63+
/// * [`Status::DEVICE_ERROR`]
64+
/// * [`Status::VOLUME_CORRUPTED`]
65+
/// * [`Status::WRITE_PROTECTED`]
66+
/// * [`Status::ACCESS_DENIED`]
67+
/// * [`Status::OUT_OF_RESOURCES`]
68+
/// * [`Status::VOLUME_FULL`]
7069
fn open(
7170
&mut self,
7271
filename: &CStr16,
@@ -111,17 +110,16 @@ pub trait File: Sized {
111110
/// The buffer must be aligned on an `<Info as Align>::alignment()` boundary.
112111
///
113112
/// # Arguments
114-
/// * `buffer` Buffer that the information should be written into
113+
/// * `buffer`: Buffer that the information should be written into
115114
///
116115
/// # Errors
117-
///
118116
/// See section `EFI_FILE_PROTOCOL.GetInfo()` in the UEFI Specification for more details.
119117
///
120-
/// * [`uefi::Status::UNSUPPORTED`]
121-
/// * [`uefi::Status::NO_MEDIA`]
122-
/// * [`uefi::Status::DEVICE_ERROR`]
123-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
124-
/// * [`uefi::Status::BUFFER_TOO_SMALL`]
118+
/// * [`Status::UNSUPPORTED`]
119+
/// * [`Status::NO_MEDIA`]
120+
/// * [`Status::DEVICE_ERROR`]
121+
/// * [`Status::VOLUME_CORRUPTED`]
122+
/// * [`Status::BUFFER_TOO_SMALL`]
125123
fn get_info<'buf, Info: FileProtocolInfo + ?Sized>(
126124
&mut self,
127125
buffer: &'buf mut [u8],
@@ -156,20 +154,19 @@ pub trait File: Sized {
156154
/// `FileProtocolInfo` type documentation.
157155
///
158156
/// # Arguments
159-
/// * `info` Info that should be set for the file
157+
/// * `info`: Info that should be set for the file
160158
///
161159
/// # Errors
162-
///
163160
/// See section `EFI_FILE_PROTOCOL.SetInfo()` in the UEFI Specification for more details.
164161
///
165-
/// * [`uefi::Status::UNSUPPORTED`]
166-
/// * [`uefi::Status::NO_MEDIA`]
167-
/// * [`uefi::Status::DEVICE_ERROR`]
168-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
169-
/// * [`uefi::Status::WRITE_PROTECTED`]
170-
/// * [`uefi::Status::ACCESS_DENIED`]
171-
/// * [`uefi::Status::VOLUME_FULL`]
172-
/// * [`uefi::Status::BAD_BUFFER_SIZE`]
162+
/// * [`Status::UNSUPPORTED`]
163+
/// * [`Status::NO_MEDIA`]
164+
/// * [`Status::DEVICE_ERROR`]
165+
/// * [`Status::VOLUME_CORRUPTED`]
166+
/// * [`Status::WRITE_PROTECTED`]
167+
/// * [`Status::ACCESS_DENIED`]
168+
/// * [`Status::VOLUME_FULL`]
169+
/// * [`Status::BAD_BUFFER_SIZE`]
173170
fn set_info<Info: FileProtocolInfo + ?Sized>(&mut self, info: &Info) -> Result {
174171
let info_ptr = ptr::from_ref(info).cast::<c_void>();
175172
let info_size = size_of_val(info);
@@ -179,15 +176,14 @@ pub trait File: Sized {
179176
/// Flushes all modified data associated with the file handle to the device
180177
///
181178
/// # Errors
182-
///
183179
/// See section `EFI_FILE_PROTOCOL.Flush()` in the UEFI Specification for more details.
184180
///
185-
/// * [`uefi::Status::NO_MEDIA`]
186-
/// * [`uefi::Status::DEVICE_ERROR`]
187-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
188-
/// * [`uefi::Status::WRITE_PROTECTED`]
189-
/// * [`uefi::Status::ACCESS_DENIED`]
190-
/// * [`uefi::Status::VOLUME_FULL`]
181+
/// * [`Status::NO_MEDIA`]
182+
/// * [`Status::DEVICE_ERROR`]
183+
/// * [`Status::VOLUME_CORRUPTED`]
184+
/// * [`Status::WRITE_PROTECTED`]
185+
/// * [`Status::ACCESS_DENIED`]
186+
/// * [`Status::VOLUME_FULL`]
191187
fn flush(&mut self) -> Result {
192188
unsafe { (self.imp().flush)(self.imp()) }.to_result()
193189
}

‎uefi/src/proto/media/file/regular.rs

Lines changed: 13 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -31,18 +31,16 @@ impl RegularFile {
3131
/// actually read.
3232
///
3333
/// # Arguments
34-
/// * `buffer` The target buffer of the read operation
34+
/// * `buffer`: The target buffer of the read operation
3535
///
3636
/// # Errors
37-
///
3837
/// See section `EFI_FILE_PROTOCOL.Read()` in the UEFI Specification for more details.
3938
///
40-
/// * [`uefi::Status::NO_MEDIA`]
41-
/// * [`uefi::Status::DEVICE_ERROR`]
42-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
39+
/// * [`Status::NO_MEDIA`]
40+
/// * [`Status::DEVICE_ERROR`]
41+
/// * [`Status::VOLUME_CORRUPTED`]
4342
///
4443
/// # Quirks
45-
///
4644
/// Some UEFI implementations have a bug where large reads will incorrectly
4745
/// return an error. This function avoids that bug by reading in chunks of
4846
/// no more than 1 MiB. This is handled internally within the function;
@@ -88,15 +86,14 @@ impl RegularFile {
8886
/// * `buffer` Buffer to write to file
8987
///
9088
/// # Errors
91-
///
9289
/// See section `EFI_FILE_PROTOCOL.Write()` in the UEFI Specification for more details.
9390
///
94-
/// * [`uefi::Status::NO_MEDIA`]
95-
/// * [`uefi::Status::DEVICE_ERROR`]
96-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
97-
/// * [`uefi::Status::WRITE_PROTECTED`]
98-
/// * [`uefi::Status::ACCESS_DENIED`]
99-
/// * [`uefi::Status::VOLUME_FULL`]
91+
/// * [`Status::NO_MEDIA`]
92+
/// * [`Status::DEVICE_ERROR`]
93+
/// * [`Status::VOLUME_CORRUPTED`]
94+
/// * [`Status::WRITE_PROTECTED`]
95+
/// * [`Status::ACCESS_DENIED`]
96+
/// * [`Status::VOLUME_FULL`]
10097
pub fn write(&mut self, buffer: &[u8]) -> Result<(), usize> {
10198
let mut buffer_size = buffer.len();
10299
unsafe { (self.imp().write)(self.imp(), &mut buffer_size, buffer.as_ptr().cast()) }
@@ -106,10 +103,9 @@ impl RegularFile {
106103
/// Get the file's current position
107104
///
108105
/// # Errors
109-
///
110106
/// See section `EFI_FILE_PROTOCOL.GetPosition()` in the UEFI Specification for more details.
111107
///
112-
/// * [`uefi::Status::DEVICE_ERROR`]
108+
/// * [`Status::DEVICE_ERROR`]
113109
pub fn get_position(&mut self) -> Result<u64> {
114110
let mut pos = 0u64;
115111
unsafe { (self.imp().get_position)(self.imp(), &mut pos) }.to_result_with_val(|| pos)
@@ -123,13 +119,12 @@ impl RegularFile {
123119
/// Using a position of RegularFile::END_OF_FILE will seek to the end of the file.
124120
///
125121
/// # Arguments
126-
/// * `position` The new absolution position of the file handle
122+
/// * `position`: The new absolution position of the file handle
127123
///
128124
/// # Errors
129-
///
130125
/// See section `EFI_FILE_PROTOCOL.SetPosition()` in the UEFI Specification for more details.
131126
///
132-
/// * [`uefi::Status::DEVICE_ERROR`]
127+
/// * [`Status::DEVICE_ERROR`]
133128
pub fn set_position(&mut self, position: u64) -> Result {
134129
unsafe { (self.imp().set_position)(self.imp(), position) }.to_result()
135130
}

‎uefi/src/proto/media/fs.rs

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
55
use super::file::{Directory, FileHandle};
66
use crate::proto::unsafe_protocol;
7+
#[cfg(doc)]
8+
use crate::Status;
79
use crate::{Result, StatusExt};
810
use core::ptr;
911
use uefi_raw::protocol::file_system::SimpleFileSystemProtocol;
@@ -39,13 +41,13 @@ impl SimpleFileSystem {
3941
/// `EFI_SIMPLE_FILE SYSTEM_PROTOCOL.OpenVolume()` (this has a space in between FILE and
4042
/// SYSTEM; it could be a typo in the UEFI spec).
4143
///
42-
/// * [`uefi::Status::UNSUPPORTED`]
43-
/// * [`uefi::Status::NO_MEDIA`]
44-
/// * [`uefi::Status::DEVICE_ERROR`]
45-
/// * [`uefi::Status::VOLUME_CORRUPTED`]
46-
/// * [`uefi::Status::ACCESS_DENIED`]
47-
/// * [`uefi::Status::OUT_OF_RESOURCES`]
48-
/// * [`uefi::Status::MEDIA_CHANGED`]
44+
/// * [`Status::UNSUPPORTED`]
45+
/// * [`Status::NO_MEDIA`]
46+
/// * [`Status::DEVICE_ERROR`]
47+
/// * [`Status::VOLUME_CORRUPTED`]
48+
/// * [`Status::ACCESS_DENIED`]
49+
/// * [`Status::OUT_OF_RESOURCES`]
50+
/// * [`Status::MEDIA_CHANGED`]
4951
pub fn open_volume(&mut self) -> Result<Directory> {
5052
let mut ptr = ptr::null_mut();
5153
unsafe { (self.0.open_volume)(&mut self.0, &mut ptr) }

‎uefi/src/proto/media/load_file.rs

Lines changed: 21 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -41,27 +41,23 @@ pub struct LoadFile(LoadFileProtocol);
4141
impl LoadFile {
4242
/// Causes the driver to load a specified file.
4343
///
44-
/// # Parameters
45-
/// - `file_path` The device specific path of the file to load.
46-
/// - `boot_policy` The [`BootPolicy`] to use.
44+
/// # Arguments
45+
/// - `file_path`: The device specific path of the file to load.
46+
/// - `boot_policy`: The [`BootPolicy`] to use.
4747
///
4848
/// # Errors
49-
/// - [`Status::SUCCESS`] The file was loaded.
50-
/// - [`Status::UNSUPPORTED`] The device does not support the
49+
/// - [`Status::UNSUPPORTED`] when the device does not support the
5150
/// provided BootPolicy.
52-
/// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
53-
/// path, or BufferSize is NULL.
54-
/// - [`Status::NO_MEDIA`] No medium was present to load the file.
55-
/// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
51+
/// - [`Status::INVALID_PARAMETER`] the `file_path` is not a valid
52+
/// [`DevicePath`]
53+
/// - [`Status::NO_MEDIA`] when no medium was present to load the file.
54+
/// - [`Status::DEVICE_ERROR`] when the file was not loaded due to a
5655
/// device error.
57-
/// - [`Status::NO_RESPONSE`] The remote system did not respond.
58-
/// - [`Status::NOT_FOUND`] The file was not found.
59-
/// - [`Status::ABORTED`] The file load process was manually
56+
/// - [`Status::NO_RESPONSE`] when the remote system did not respond.
57+
/// - [`Status::NOT_FOUND`] when the file was not found.
58+
/// - [`Status::ABORTED`] when the file load process was manually
6059
/// cancelled.
61-
/// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
62-
/// read the current directory entry. BufferSize has been updated with the
63-
/// size needed to complete the request.
64-
/// - [`Status::WARN_FILE_SYSTEM`] The resulting Buffer contains
60+
/// - [`Status::WARN_FILE_SYSTEM`] when the resulting buffer contains
6561
/// UEFI-compliant file system.
6662
///
6763
/// [`BootPolicy`]: uefi::proto::BootPolicy
@@ -117,24 +113,19 @@ pub struct LoadFile2(LoadFile2Protocol);
117113
impl LoadFile2 {
118114
/// Causes the driver to load a specified file.
119115
///
120-
/// # Parameters
121-
/// - `file_path` The device specific path of the file to load.
116+
/// # Arguments
117+
/// - `file_path`: The device specific path of the file to load.
122118
///
123119
/// # Errors
124-
/// - [`Status::SUCCESS`] The file was loaded.
125-
/// - [`Status::UNSUPPORTED`] BootPolicy is TRUE.
126-
/// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
127-
/// path, or BufferSize is NULL.
128-
/// - [`Status::NO_MEDIA`] No medium was present to load the file.
129-
/// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
120+
/// - [`Status::INVALID_PARAMETER`] when `file_path` is not a valid device
121+
/// path, or the buffer size is NULL.
122+
/// - [`Status::NO_MEDIA`] when no medium was present to load the file.
123+
/// - [`Status::DEVICE_ERROR`] when the file was not loaded due to a
130124
/// device error.
131-
/// - [`Status::NO_RESPONSE`] The remote system did not respond.
132-
/// - [`Status::NOT_FOUND`] The file was not found.
133-
/// - [`Status::ABORTED`] The file load process was manually
125+
/// - [`Status::NO_RESPONSE`] when the remote system did not respond.
126+
/// - [`Status::NOT_FOUND`] when the file was not found.
127+
/// - [`Status::ABORTED`] when the file load process was manually
134128
/// cancelled.
135-
/// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
136-
/// read the current directory entry. BufferSize has been updated with the
137-
/// size needed to complete the request.
138129
#[cfg(feature = "alloc")]
139130
#[allow(clippy::extra_unused_lifetimes)] // false positive, it is used
140131
pub fn load_file<'a>(&mut self, file_path: &DevicePath) -> Result<Box<[u8]>> {

‎uefi/src/proto/tcg/v1.rs

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,6 @@ impl PcrEvent {
103103
/// Create a new `PcrEvent` using a byte buffer for storage.
104104
///
105105
/// # Errors
106-
///
107106
/// Returns [`Status::BUFFER_TOO_SMALL`] if the `buffer` is not large
108107
/// enough. The required size will be returned in the error data.
109108
///
@@ -147,7 +146,6 @@ impl PcrEvent {
147146
/// Create a new `PcrEvent` in a [`Box`].
148147
///
149148
/// # Errors
150-
///
151149
/// Returns [`Status::INVALID_PARAMETER`] if the `event_data` size is too
152150
/// large.
153151
#[cfg(feature = "alloc")]

‎uefi/src/proto/tcg/v2.rs

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,6 @@ impl PcrEventInputs {
130130
/// Create a new `PcrEventInputs` using a byte buffer for storage.
131131
///
132132
/// # Errors
133-
///
134133
/// Returns [`Status::BUFFER_TOO_SMALL`] if the `buffer` is not large
135134
/// enough. The required size will be returned in the error data.
136135
///
@@ -174,7 +173,6 @@ impl PcrEventInputs {
174173
/// Create a new `PcrEventInputs` in a [`Box`].
175174
///
176175
/// # Errors
177-
///
178176
/// Returns [`Status::INVALID_PARAMETER`] if the `event_data` size is too
179177
/// large.
180178
#[cfg(feature = "alloc")]

‎uefi/src/runtime.rs

Lines changed: 43 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,11 @@ pub unsafe fn set_time(time: &Time) -> Result {
8484
/// not exist, or `Err` if the existence of the variable could not be determined.
8585
///
8686
/// # Errors
87-
///
88-
/// * [`Status::DEVICE_ERROR`]: variable could not be read due to a hardware error.
89-
/// * [`Status::SECURITY_VIOLATION`]: variable could not be read due to an
87+
/// * [`Status::DEVICE_ERROR`] if the variable could not be read due to
88+
/// hardware error.
89+
/// * [`Status::SECURITY_VIOLATION`] if the variable could not be read due to an
9090
/// authentication error.
91-
/// * [`Status::UNSUPPORTED`]: this platform does not support variable storage
91+
/// * [`Status::UNSUPPORTED`] if this platform does not support variable storage
9292
/// after exiting boot services.
9393
pub fn variable_exists(name: &CStr16, vendor: &VariableVendor) -> Result<bool> {
9494
let rt = runtime_services_raw_panicking();
@@ -126,14 +126,14 @@ pub fn variable_exists(name: &CStr16, vendor: &VariableVendor) -> Result<bool> {
126126
/// `buf`) and the variable's attributes.
127127
///
128128
/// # Errors
129-
///
130-
/// * [`Status::NOT_FOUND`]: variable was not found.
131-
/// * [`Status::BUFFER_TOO_SMALL`]: `buf` is not large enough. The required size
132-
/// will be returned in the error data.
133-
/// * [`Status::DEVICE_ERROR`]: variable could not be read due to a hardware error.
134-
/// * [`Status::SECURITY_VIOLATION`]: variable could not be read due to an
129+
/// * [`Status::NOT_FOUND`] if the variable was not found.
130+
/// * [`Status::BUFFER_TOO_SMALL`] if `buf` is not large enough. The required
131+
/// size will be returned in the error data.
132+
/// * [`Status::DEVICE_ERROR`] if the variable could not be read due to a
133+
/// hardware error.
134+
/// * [`Status::SECURITY_VIOLATION`] if the variable could not be read due to an
135135
/// authentication error.
136-
/// * [`Status::UNSUPPORTED`]: this platform does not support variable storage
136+
/// * [`Status::UNSUPPORTED`] if this platform does not support variable storage
137137
/// after exiting boot services.
138138
pub fn get_variable<'buf>(
139139
name: &CStr16,
@@ -165,12 +165,12 @@ pub fn get_variable<'buf>(
165165
/// Gets the contents and attributes of a variable.
166166
///
167167
/// # Errors
168-
///
169-
/// * [`Status::NOT_FOUND`]: variable was not found.
170-
/// * [`Status::DEVICE_ERROR`]: variable could not be read due to a hardware error.
171-
/// * [`Status::SECURITY_VIOLATION`]: variable could not be read due to an
168+
/// * [`Status::NOT_FOUND`] if the variable was not found.
169+
/// * [`Status::DEVICE_ERROR`] if the variable could not be read due to a
170+
/// hardware error.
171+
/// * [`Status::SECURITY_VIOLATION`] if the variable could not be read due to an
172172
/// authentication error.
173-
/// * [`Status::UNSUPPORTED`]: this platform does not support variable storage
173+
/// * [`Status::UNSUPPORTED`] if this platform does not support variable storage
174174
/// after exiting boot services.
175175
#[cfg(feature = "alloc")]
176176
pub fn get_variable_boxed(
@@ -213,9 +213,7 @@ pub fn get_variable_boxed(
213213
/// [`CStr16::from_u16_with_nul`].
214214
///
215215
/// # Errors
216-
///
217-
/// * [`Status::NOT_FOUND`]: indicates end of iteration, the last variable keys
218-
/// was retrieved by the previous call to `get_next_variable_key`.
216+
/// * [`Status::NOT_FOUND`] if no further variables are found.
219217
/// * [`Status::BUFFER_TOO_SMALL`]: `name` is not large enough. The required
220218
/// size (in `u16` characters, not bytes) will be returned in the error data.
221219
/// * [`Status::INVALID_PARAMETER`]: `name` does not contain a null character, or
@@ -347,15 +345,14 @@ impl Iterator for VariableKeys {
347345
/// mode if the firmware requires a reboot for that operation.
348346
///
349347
/// # Errors
350-
///
351-
/// * [`Status::INVALID_PARAMETER`]: invalid attributes, name, or vendor.
352-
/// * [`Status::OUT_OF_RESOURCES`]: not enough storage is available to hold
348+
/// * [`Status::INVALID_PARAMETER`] if `name` or `vendor` are invalid.
349+
/// * [`Status::OUT_OF_RESOURCES`] if not enough storage is available to hold
353350
/// the variable.
354-
/// * [`Status::WRITE_PROTECTED`]: variable is read-only.
355-
/// * [`Status::SECURITY_VIOLATION`]: variable could not be written due to an
356-
/// authentication error.
357-
/// * [`Status::NOT_FOUND`]: attempted to update a non-existent variable.
358-
/// * [`Status::UNSUPPORTED`]: this platform does not support variable storage
351+
/// * [`Status::WRITE_PROTECTED`] if the variable is read-only.
352+
/// * [`Status::SECURITY_VIOLATION`] if the variable could not be written due to
353+
/// an authentication error.
354+
/// * [`Status::NOT_FOUND`] if the variable is non-existent.
355+
/// * [`Status::UNSUPPORTED`] if this platform does not support variable storage
359356
/// after exiting boot services.
360357
pub fn set_variable(
361358
name: &CStr16,
@@ -381,13 +378,12 @@ pub fn set_variable(
381378
/// Deletes a UEFI variable.
382379
///
383380
/// # Errors
384-
///
385-
/// * [`Status::INVALID_PARAMETER`]: invalid name or vendor.
386-
/// * [`Status::WRITE_PROTECTED`]: variable is read-only.
387-
/// * [`Status::SECURITY_VIOLATION`]: variable could not be deleted due to an
388-
/// authentication error.
389-
/// * [`Status::NOT_FOUND`]: attempted to delete a non-existent variable.
390-
/// * [`Status::UNSUPPORTED`]: this platform does not support variable storage
381+
/// * [`Status::INVALID_PARAMETER`] if `name` or `vendor` are invalid.
382+
/// * [`Status::WRITE_PROTECTED`] if the variable is read-only.
383+
/// * [`Status::SECURITY_VIOLATION`] if the variable could not be written due to
384+
/// an authentication error.
385+
/// * [`Status::NOT_FOUND`] if the variable is non-existent.
386+
/// * [`Status::UNSUPPORTED`] if this platform does not support variable storage
391387
/// after exiting boot services.
392388
pub fn delete_variable(name: &CStr16, vendor: &VariableVendor) -> Result {
393389
set_variable(name, vendor, VariableAttributes::empty(), &[])
@@ -429,18 +425,17 @@ pub fn query_variable_info(attributes: VariableAttributes) -> Result<VariableSto
429425
///
430426
/// Capsules are most commonly used to update system firmware.
431427
///
432-
/// # Errors
433-
///
434-
/// * [`Status::INVALID_PARAMETER`]: zero capsules were provided, or the
428+
/// # Errors///
429+
/// * [`Status::INVALID_PARAMETER`] if zero capsules were provided, or the
435430
/// capsules are invalid.
436-
/// * [`Status::DEVICE_ERROR`]: the capsule update was started but failed to a
437-
/// device error.
438-
/// * [`Status::OUT_OF_RESOURCES`]: before exiting boot services, indicates the
431+
/// * [`Status::DEVICE_ERROR`] if the capsule update was started but failed due
432+
/// to a device error.
433+
/// * [`Status::OUT_OF_RESOURCES`] if before exiting boot services, the
439434
/// capsule is compatible with the platform but there are insufficient
440435
/// resources to complete the update. After exiting boot services, indicates
441436
/// the capsule is compatible with the platform but can only be processed
442437
/// before exiting boot services.
443-
/// * [`Status::UNSUPPORTED`]: this platform does not support capsule updates
438+
/// * [`Status::UNSUPPORTED`] if this platform does not support capsule updates
444439
/// after exiting boot services.
445440
pub fn update_capsule(
446441
capsule_header_array: &[&CapsuleHeader],
@@ -464,15 +459,14 @@ pub fn update_capsule(
464459
/// See [`CapsuleInfo`] for details of the information returned.
465460
///
466461
/// # Errors
467-
///
468-
/// * [`Status::OUT_OF_RESOURCES`]: before exiting boot services, indicates the
462+
/// * [`Status::OUT_OF_RESOURCES`] if before exiting boot services, the
469463
/// capsule is compatible with the platform but there are insufficient
470464
/// resources to complete the update. After exiting boot services, indicates
471465
/// the capsule is compatible with the platform but can only be processed
472466
/// before exiting boot services.
473-
/// * [`Status::UNSUPPORTED`]: either the capsule type is not supported by this
474-
/// platform, or the platform does not support capsule updates after exiting
475-
/// boot services.
467+
/// * [`Status::UNSUPPORTED`] if either the capsule type is not supported by
468+
/// this platform, or the platform does not support capsule updates after
469+
/// exiting boot services.
476470
pub fn query_capsule_capabilities(capsule_header_array: &[&CapsuleHeader]) -> Result<CapsuleInfo> {
477471
let rt = runtime_services_raw_panicking();
478472
let rt = unsafe { rt.as_ref() };
@@ -527,12 +521,11 @@ pub fn reset(reset_type: ResetType, status: Status, data: Option<&[u8]>) -> ! {
527521
/// The caller must ensure the memory map is valid.
528522
///
529523
/// # Errors
530-
///
531-
/// * [`Status::UNSUPPORTED`]: either boot services haven't been exited, the
524+
/// * [`Status::UNSUPPORTED`] if either boot services haven't been exited, the
532525
/// firmware's addressing mode is already virtual, or the firmware does not
533526
/// support this operation.
534-
/// * [`Status::NO_MAPPING`]: `map` is missing a required range.
535-
/// * [`Status::NOT_FOUND`]: `map` contains an address that is not in the
527+
/// * [`Status::NO_MAPPING`] if `map` is missing a required range.
528+
/// * [`Status::NOT_FOUND`] if `map` contains an address that is not in the
536529
/// current memory map.
537530
pub unsafe fn set_virtual_address_map(
538531
map: &mut [MemoryDescriptor],

‎xtask/src/cargo.rs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -113,9 +113,10 @@ impl Feature {
113113
}
114114

115115
/// Set of features that enables more code in the root uefi crate.
116-
/// # Parameters
117-
/// - `include_unstable` - add all functionality behind the `unstable` feature
118-
/// - `runtime_features` - add all functionality that effect the runtime of Rust
116+
///
117+
/// # Arguments
118+
/// - `include_unstable`: add all functionality behind the `unstable` feature
119+
/// - `runtime_features`: add all functionality that effect the runtime of Rust
119120
pub fn more_code(include_unstable: bool, runtime_features: bool) -> Vec<Self> {
120121
let mut base_features = vec![Self::Alloc, Self::LogDebugcon, Self::Logger];
121122
if include_unstable {

0 commit comments

Comments
 (0)
Please sign in to comment.