Skip to content

Commit c7964e5

Browse files
phip1611phip1611
committed
doc: streamline
Streamline all `# Errors` and `# Arguments`. This is about the style, not the content. No major changes have been made with a few small exceptions, where I deleted obviously wrong or irrelevant error codes. The advantage of this streamlined and consistent style, is that new contributions can follow the guideline.
1 parent 14ef880 commit c7964e5

File tree

18 files changed

+346
-370
lines changed

18 files changed

+346
-370
lines changed

Diff for: ‎uefi/src/boot.rs

+82-107
Large diffs are not rendered by default.

Diff for: ‎uefi/src/data_types/strs.rs

-2
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.

Diff for: ‎uefi/src/mem/memory_map/impl_.rs

+1-1
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> {

Diff for: ‎uefi/src/proto/console/pointer/mod.rs

+4-3
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
}

Diff for: ‎uefi/src/proto/console/text/input.rs

+6-6
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.
19-
///
17+
/// # Arguments
18+
/// - `extended_verification`: Request that UEFI performs an extended check
19+
/// and reset of the input device.
20+
///
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

Diff for: ‎uefi/src/proto/device_path/mod.rs

-1
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.

Diff for: ‎uefi/src/proto/media/block.rs

+29-26
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
//! Block I/O protocols.
44
55
use crate::proto::unsafe_protocol;
6-
use crate::{Result, StatusExt};
6+
use crate::{Result, Status, StatusExt};
77

88
pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
99

@@ -23,11 +23,11 @@ impl BlockIO {
2323
/// Resets the block device hardware.
2424
///
2525
/// # Arguments
26-
/// * `extended_verification` Indicates that the driver may perform a more
27-
/// exhaustive verification operation of the device during reset.
26+
/// * `extended_verification`: Request that UEFI performs an extended check
27+
/// and reset of the input device.
2828
///
2929
/// # Errors
30-
/// * `uefi::Status::DEVICE_ERROR` The block device is not functioning
30+
/// * [`Status::DEVICE_ERROR`] if the block device is not functioning
3131
/// correctly and could not be reset.
3232
pub fn reset(&mut self, extended_verification: bool) -> Result {
3333
unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
@@ -36,18 +36,20 @@ impl BlockIO {
3636
/// Read the requested number of blocks from the device.
3737
///
3838
/// # 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
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
4242
///
4343
/// # 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
44+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
45+
/// attempting to perform the read operation.
46+
/// * [`Status::NO_MEDIA`] when there is no media in the device.
47+
/// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
48+
/// media.
49+
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
50+
/// a multiple of the intrinsic block size of the device.
51+
/// * [`Status::INVALID_PARAMETER`] when the read request contains LBAs
52+
/// that are not valid, or the buffer is not on
5153
/// proper alignment.
5254
pub fn read_blocks(&self, media_id: u32, lba: Lba, buffer: &mut [u8]) -> Result {
5355
let buffer_size = buffer.len();
@@ -66,20 +68,21 @@ impl BlockIO {
6668
/// Writes the requested number of blocks to the device.
6769
///
6870
/// # 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
71+
/// * `media_id`: The media ID that the write request is for.
72+
/// * `lba`: The starting logical block address to be written.
73+
/// * `buffer`: Buffer to be written
7274
///
7375
/// # 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.
76+
/// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
77+
/// * [`Status::NO_MEDIA`] when there is no media in the device.
78+
/// * [`Status::MEDIA_CHANGED`] when the `media_id` is not for the
79+
/// current media.
80+
/// * [`Status::DEVICE_ERROR`] when the device reported an error while
81+
/// attempting to perform the write operation.
82+
/// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
83+
/// a multiple of the intrinsic block size of the device.
84+
/// * [`Status::INVALID_PARAMETER`] The write request contains LBAs that
85+
/// are not valid, or the buffer is not on proper alignment.
8386
pub fn write_blocks(&mut self, media_id: u32, lba: Lba, buffer: &[u8]) -> Result {
8487
let buffer_size = buffer.len();
8588
unsafe {

Diff for: ‎uefi/src/proto/media/disk.rs

+70-53
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()

0 commit comments

Comments
 (0)