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.

Author: phip1611

uefi/src/boot.rs

@@ -362,7 +362,6 @@ impl CStr16 {
     /// Creates a `&CStr16` from a u16 slice, stopping at the first nul character.
     ///
     /// # Errors
-    ///
     /// An error is returned if the slice contains invalid UCS-2 characters, or
     /// if the slice does not contain any nul character.
     pub fn from_u16_until_nul(codes: &[u16]) -> Result<&Self, FromSliceUntilNulError> {
@@ -411,7 +410,6 @@ impl CStr16 {
     /// Creates a `&CStr16` from a [`Char16`] slice, stopping at the first nul character.
     ///
     /// # Errors
-    ///
     /// An error is returned if the slice does not contain any nul character.
     pub fn from_char16_until_nul(chars: &[Char16]) -> Result<&Self, FromSliceUntilNulError> {
         // Find the index of the first null char.

uefi/src/data_types/strs.rs

@@ -275,7 +275,7 @@ pub(crate) struct MemoryMapBackingMemory(NonNull<[u8]>);
 impl MemoryMapBackingMemory {
     /// Constructs a new [`MemoryMapBackingMemory`].
     ///
-    /// # Parameters
+    /// # Arguments
     /// - `memory_type`: The memory type for the memory map allocation.
     ///   Typically, [`MemoryType::LOADER_DATA`] for regular UEFI applications.
     pub(crate) fn new(memory_type: MemoryType) -> crate::Result<Self> {

uefi/src/mem/memory_map/impl_.rs

@@ -16,11 +16,12 @@ impl Pointer {
     /// Resets the pointer device hardware.
     ///
     /// # Arguments
-    /// The `extended_verification` parameter is used to request that UEFI
-    /// performs an extended check and reset of the input device.
+    /// - `extended_verification`: Request that UEFI performs an extended check
+    ///   and reset of the input device.
     ///
     /// # Errors
-    /// - `DeviceError` if the device is malfunctioning and cannot be reset.
+    /// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot be
+    ///   reset.
     pub fn reset(&mut self, extended_verification: bool) -> Result {
         unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
     }

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

@@ -14,12 +14,13 @@ pub struct Input(SimpleTextInputProtocol);
 impl Input {
     /// Resets the input device hardware.
     ///
-    /// The `extended_verification` parameter is used to request that UEFI
-    /// performs an extended check and reset of the input device.
+    /// # Arguments
+    /// - `extended_verification`: Request that UEFI performs an extended check
+    ///   and reset of the input device.
     ///
     /// # Errors
-    ///
-    /// - `DeviceError` if the device is malfunctioning and cannot be reset.
+    /// - [`Status::DEVICE_ERROR`] if the device is malfunctioning and cannot
+    ///   be reset.
     pub fn reset(&mut self, extended_verification: bool) -> Result {
         unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
     }
@@ -33,7 +34,6 @@ impl Input {
     /// [`wait_for_key_event`]: Self::wait_for_key_event
     ///
     /// # Errors
-    ///
     /// - [`Status::DEVICE_ERROR`] if there was an issue with the input device
     ///
     /// # Examples

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

@@ -401,7 +401,6 @@ impl DevicePath {
     /// end-entire node.
     ///
     /// # Errors
-    ///
     /// The [`ByteConversionError::InvalidLength`] error will be returned
     /// when the length of the given bytes slice cannot contain the full
     /// [`DevicePath`] represented by the slice.

uefi/src/proto/device_path/mod.rs

@@ -3,6 +3,8 @@
 //! Block I/O protocols.
 
 use crate::proto::unsafe_protocol;
+#[cfg(doc)]
+use crate::Status;
 use crate::{Result, StatusExt};
 
 pub use uefi_raw::protocol::block::{BlockIoProtocol, Lba};
@@ -23,11 +25,11 @@ impl BlockIO {
     /// Resets the block device hardware.
     ///
     /// # Arguments
-    /// * `extended_verification` Indicates that the driver may perform a more
-    ///   exhaustive verification operation of the device during reset.
+    /// * `extended_verification`: Request that UEFI performs an extended check
+    ///   and reset of the input device.
     ///
     /// # Errors
-    /// * `uefi::Status::DEVICE_ERROR`  The block device is not functioning
+    /// * [`Status::DEVICE_ERROR`] if the block device is not functioning
     ///   correctly and could not be reset.
     pub fn reset(&mut self, extended_verification: bool) -> Result {
         unsafe { (self.0.reset)(&mut self.0, extended_verification.into()) }.to_result()
@@ -36,18 +38,20 @@ impl BlockIO {
     /// Read the requested number of blocks from the device.
     ///
     /// # Arguments
-    /// * `media_id` - The media ID that the read request is for.
-    /// * `lba` - The starting logical block address to read from on the device.
-    /// * `buffer` - The target buffer of the read operation
+    /// * `media_id`: The media ID that the read request is for.
+    /// * `lba`: The starting logical block address to read from on the device.
+    /// * `buffer`: The target buffer of the read operation
     ///
     /// # Errors
-    /// * `uefi::Status::DEVICE_ERROR`       The device reported an error while attempting to perform the read
-    ///   operation.
-    /// * `uefi::Status::NO_MEDIA`           There is no media in the device.
-    /// * `uefi::Status::MEDIA_CHANGED`      The `media_id` is not for the current media.
-    /// * `uefi::Status::BAD_BUFFER_SIZE`    The buffer size parameter is not a multiple of the intrinsic block size of
-    ///   the device.
-    /// * `uefi::Status::INVALID_PARAMETER`  The read request contains LBAs that are not valid, or the buffer is not on
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   attempting to perform the read operation.
+    /// * [`Status::NO_MEDIA`] when there is no media in the device.
+    /// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
+    ///   media.
+    /// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
+    ///   a multiple of the intrinsic block size of the device.
+    /// * [`Status::INVALID_PARAMETER`] when the read request contains LBAs
+    ///   that are not valid, or the buffer is not on
     ///   proper alignment.
     pub fn read_blocks(&self, media_id: u32, lba: Lba, buffer: &mut [u8]) -> Result {
         let buffer_size = buffer.len();
@@ -66,20 +70,21 @@ impl BlockIO {
     /// Writes the requested number of blocks to the device.
     ///
     /// # Arguments
-    /// * `media_id`    The media ID that the write request is for.
-    /// * `lba`         The starting logical block address to be written.
-    /// * `buffer`      Buffer to be written
+    /// * `media_id`: The media ID that the write request is for.
+    /// * `lba`: The starting logical block address to be written.
+    /// * `buffer`: Buffer to be written
     ///
     /// # Errors
-    /// * `uefi::Status::WRITE_PROTECTED`       The device cannot be written to.
-    /// * `uefi::Status::NO_MEDIA`              There is no media in the device.
-    /// * `uefi::Status::MEDIA_CHANGED`         The `media_id` is not for the current media.
-    /// * `uefi::Status::DEVICE_ERROR`          The device reported an error while attempting to perform the write
-    ///   operation.
-    /// * `uefi::Status::BAD_BUFFER_SIZE`       The buffer size parameter is not a multiple of the intrinsic block size
-    ///   of the device.
-    /// * `uefi::Status::INVALID_PARAMETER`     The write request contains LBAs that are not valid, or the buffer is not
-    ///   on proper alignment.
+    /// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
+    /// * [`Status::NO_MEDIA`] when there is no media in the device.
+    /// * [`Status::MEDIA_CHANGED`] when the `media_id` is not for the
+    ///   current media.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   attempting to perform the write operation.
+    /// * [`Status::BAD_BUFFER_SIZE`] when the buffer size parameter is not
+    ///   a multiple of the intrinsic block size of the device.
+    /// * [`Status::INVALID_PARAMETER`] The write request contains LBAs that
+    ///   are not valid, or the buffer is not on proper alignment.
     pub fn write_blocks(&mut self, media_id: u32, lba: Lba, buffer: &[u8]) -> Result {
         let buffer_size = buffer.len();
         unsafe {

uefi/src/proto/media/block.rs

@@ -22,16 +22,19 @@ pub struct DiskIo(DiskIoProtocol);
 impl DiskIo {
     /// Reads bytes from the disk device.
     ///
-    /// # Arguments:
-    /// * `media_id` - ID of the medium to be read.
-    /// * `offset` - Starting byte offset on the logical block I/O device to read from.
-    /// * `buffer` - Pointer to a buffer to read into.
+    /// # Arguments
+    /// * `media_id`: ID of the medium to be read.
+    /// * `offset`: Starting byte offset on the logical block I/O device to read from.
+    /// * `buffer`: Pointer to a buffer to read into.
     ///
-    /// # Errors:
-    /// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
-    /// * [`Status::DEVICE_ERROR`]      The device reported an error while performing the read operation.
-    /// * [`Status::NO_MEDIA`]          There is no medium in the device.
-    /// * [`Status::MEDIA_CHANGED`]     `media_id` is not for the current medium.
+    /// # Errors
+    /// * [`Status::INVALID_PARAMETER`] when the read request contains device
+    ///   addresses that are not valid for the device.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   performing the read operation.
+    /// * [`Status::NO_MEDIA`] when there is no medium in the device.
+    /// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
+    ///   medium.
     pub fn read_disk(&self, media_id: u32, offset: u64, buffer: &mut [u8]) -> Result {
         unsafe {
             (self.0.read_disk)(
@@ -47,17 +50,20 @@ impl DiskIo {
 
     /// Writes bytes to the disk device.
     ///
-    /// # Arguments:
-    /// * `media_id` - ID of the medium to be written.
-    /// * `offset` - Starting byte offset on the logical block I/O device to write to.
-    /// * `buffer` - Pointer to a buffer to write from.
+    /// # Arguments
+    /// * `media_id`: ID of the medium to be written.
+    /// * `offset`: Starting byte offset on the logical block I/O device to write to.
+    /// * `buffer`: Pointer to a buffer to write from.
     ///
-    /// # Errors:
-    /// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
-    /// * [`Status::DEVICE_ERROR`]      The device reported an error while performing the write operation.
-    /// * [`Status::NO_MEDIA`]          There is no medium in the device.
-    /// * [`Status::MEDIA_CHANGED`]     `media_id` is not for the current medium.
-    /// * [`Status::WRITE_PROTECTED`]   The device cannot be written to.
+    /// # Errors
+    /// * [`Status::INVALID_PARAMETER`] when the write request contains device
+    ///   addresses that are not valid for the device.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   performing the write operation.
+    /// * [`Status::NO_MEDIA`] when there is no medium in the device.
+    /// * [`Status::MEDIA_CHANGED`] then `media_id` is not for the current
+    ///   medium.
+    /// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
     pub fn write_disk(&mut self, media_id: u32, offset: u64, buffer: &[u8]) -> Result {
         unsafe {
             (self.0.write_disk)(
@@ -94,32 +100,36 @@ pub struct DiskIo2(DiskIo2Protocol);
 impl DiskIo2 {
     /// Terminates outstanding asynchronous requests to the device.
     ///
-    /// # Errors:
+    /// # Errors
     /// * [`Status::DEVICE_ERROR`] The device reported an error while performing
     pub fn cancel(&mut self) -> Result {
         unsafe { (self.0.cancel)(&mut self.0) }.to_result()
     }
 
     /// Reads bytes from the disk device.
     ///
-    /// # Arguments:
-    /// * `media_id` - ID of the medium to be read from.
-    /// * `offset` - Starting byte offset on the logical block I/O device to read from.
-    /// * `token` - Transaction token for asynchronous read.
-    /// * `len` - Buffer size.
-    /// * `buffer` - Buffer to read into.
+    /// # Arguments
+    /// * `media_id`: ID of the medium to be read from.
+    /// * `offset`: Starting byte offset on the logical block I/O device to read from.
+    /// * `token`: Transaction token for asynchronous read.
+    /// * `len`: Buffer size.
+    /// * `buffer`: Buffer to read into.
     ///
     /// # Safety
     ///
     /// Because of the asynchronous nature of the disk transaction, manual lifetime
     /// tracking is required.
     ///
-    /// # Errors:
-    /// * [`Status::INVALID_PARAMETER`] The read request contains device addresses that are not valid for the device.
-    /// * [`Status::OUT_OF_RESOURCES`]  The request could not be completed due to a lack of resources.
-    /// * [`Status::MEDIA_CHANGED`]     `media_id` is not for the current medium.
-    /// * [`Status::NO_MEDIA`]          There is no medium in the device.
-    /// * [`Status::DEVICE_ERROR`]      The device reported an error while performing the read operation.
+    /// # Errors
+    /// * [`Status::INVALID_PARAMETER`] when the read request contains device
+    ///   addresses that are not valid for the device.
+    /// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
+    ///   due to a lack of resources.
+    /// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
+    ///   medium.
+    /// * [`Status::NO_MEDIA`] when there is no medium in the device.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   performing the read operation.
     pub unsafe fn read_disk_raw(
         &self,
         media_id: u32,
@@ -137,25 +147,29 @@ impl DiskIo2 {
 
     /// Writes bytes to the disk device.
     ///
-    /// # Arguments:
-    /// * `media_id` - ID of the medium to write to.
-    /// * `offset` - Starting byte offset on the logical block I/O device to write to.
-    /// * `token` - Transaction token for asynchronous write.
-    /// * `len` - Buffer size.
-    /// * `buffer` - Buffer to write from.
+    /// # Arguments
+    /// * `media_id`: ID of the medium to write to.
+    /// * `offset`: Starting byte offset on the logical block I/O device to write to.
+    /// * `token`: Transaction token for asynchronous write.
+    /// * `len`: Buffer size.
+    /// * `buffer`: Buffer to write from.
     ///
     /// # Safety
     ///
     /// Because of the asynchronous nature of the disk transaction, manual lifetime
     /// tracking is required.
     ///
-    /// # Errors:
-    /// * [`Status::INVALID_PARAMETER`] The write request contains device addresses that are not valid for the device.
-    /// * [`Status::OUT_OF_RESOURCES`]  The request could not be completed due to a lack of resources.
-    /// * [`Status::MEDIA_CHANGED`      `media_id` is not for the current medium.
-    /// * [`Status::NO_MEDIA`]          There is no medium in the device.
-    /// * [`Status::DEVICE_ERROR`]      The device reported an error while performing the write operation.
-    /// * [`Status::WRITE_PROTECTED`]   The device cannot be written to.
+    /// # Errors
+    /// * [`Status::INVALID_PARAMETER`] when the write request contains device
+    ///   addresses that are not valid for the device.
+    /// * [`Status::OUT_OF_RESOURCES`]  when the request could not be completed
+    ///   due to a lack of resources.
+    /// * [`Status::MEDIA_CHANGED`] when `media_id` is not for the current
+    ///   medium.
+    /// * [`Status::NO_MEDIA`] when there is no medium in the device.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   performing the write operation.
+    /// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
     pub unsafe fn write_disk_raw(
         &mut self,
         media_id: u32,
@@ -180,15 +194,18 @@ impl DiskIo2 {
 
     /// Flushes all modified data to the physical device.
     ///
-    /// # Arguments:
-    /// * `token` - Transaction token for the asynchronous flush.
+    /// # Arguments
+    /// * `token`: Transaction token for the asynchronous flush.
     ///
-    /// # Errors:
-    /// * [`Status::OUT_OF_RESOURCES`]  The request could not be completed due to a lack of resources.
-    /// * [`Status::MEDIA_CHANGED`]     The medium in the device has changed since the last access.
-    /// * [`Status::NO_MEDIA`]          There is no medium in the device.
-    /// * [`Status::DEVICE_ERROR`]      The device reported an error while performing the flush operation.
-    /// * [`Status::WRITE_PROTECTED`]   The device cannot be written to.
+    /// # Errors
+    /// * [`Status::OUT_OF_RESOURCES`] when the request could not be completed
+    ///  due to a lack of resources.
+    /// * [`Status::MEDIA_CHANGED`] when the medium in the device has changed
+    ///   since the last access.
+    /// * [`Status::NO_MEDIA`] when there is no medium in the device.
+    /// * [`Status::DEVICE_ERROR`] when the device reported an error while
+    ///   performing the flush operation.
+    /// * [`Status::WRITE_PROTECTED`] when the device cannot be written to.
     pub fn flush_disk(&mut self, token: Option<NonNull<DiskIo2Token>>) -> Result {
         let token = opt_nonnull_to_ptr(token);
         unsafe { (self.0.flush_disk_ex)(&mut self.0, token.cast()) }.to_result()