uefi: Clean up error docs in media protocols

nicholasbishop · nicholasbishop · commit a6663726fbd7 · 2025-03-09T17:09:41.000-04:00
* Fix the path to the status values -- `uefi::status::*` does not exist, it should
  be `Status::*`.
* Drop `EFI_` prefix to match the actual `Status` constants.
* Use doc links so that incorrect names are caught by rustdoc.
* Reformat some errors to a single line for consistency.
diff --git a/uefi/src/proto/media/disk.rs b/uefi/src/proto/media/disk.rs
@@ -28,12 +28,10 @@ impl DiskIo {
     /// * `buffer` - Pointer to a buffer to read into.
     ///
     /// # Errors:
-    /// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses that
-    ///                                     are not valid for the device.
-    /// * `uefi::status::DEVICE_ERROR`      The device reported an error while performing
-    ///                                     the read operation.
-    /// * `uefi::status::NO_MEDIA`          There is no medium in the device.
-    /// * `uefi::status::MEDIA_CHANGED`     `media_id` is not for the current medium.
+    /// * [`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.
     pub fn read_disk(&self, media_id: u32, offset: u64, buffer: &mut [u8]) -> Result {
         unsafe {
             (self.0.read_disk)(
@@ -55,13 +53,11 @@ impl DiskIo {
     /// * `buffer` - Pointer to a buffer to write from.
     ///
     /// # Errors:
-    /// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses that
-    ///                                     are not valid for the device.
-    /// * `uefi::status::DEVICE_ERROR`      The device reported an error while performing
-    ///                                     the write operation.
-    /// * `uefi::status::NO_MEDIA`          There is no medium in the device.
-    /// * `uefi::status::MEDIA_CHANGED`     `media_id` is not for the current medium.
-    /// * `uefi::status::WRITE_PROTECTED`   The device cannot be written to.
+    /// * [`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.
     pub fn write_disk(&mut self, media_id: u32, offset: u64, buffer: &[u8]) -> Result {
         unsafe {
             (self.0.write_disk)(
@@ -99,7 +95,7 @@ impl DiskIo2 {
     /// Terminates outstanding asynchronous requests to the device.
     ///
     /// # Errors:
-    /// * `uefi::status::DEVICE_ERROR`  The device reported an error while performing
+    /// * [`Status::DEVICE_ERROR`]  The device reported an error while performing
     ///                                 the cancel operation.
     pub fn cancel(&mut self) -> Result {
         unsafe { (self.0.cancel)(&mut self.0) }.to_result()
@@ -120,14 +116,11 @@ impl DiskIo2 {
     /// tracking is required.
     ///
     /// # Errors:
-    /// * `uefi::status::INVALID_PARAMETER` The read request contains device addresses
-    ///                                     that are not valid for the device.
-    /// * `uefi::status::OUT_OF_RESOURCES`  The request could not be completed due to
-    ///                                     a lack of resources.
-    /// * `uefi::status::MEDIA_CHANGED`     `media_id` is not for the current medium.
-    /// * `uefi::status::NO_MEDIA`          There is no medium in the device.
-    /// * `uefi::status::DEVICE_ERROR`      The device reported an error while performing
-    ///                                     the read operation.
+    /// * [`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.
     pub unsafe fn read_disk_raw(
         &self,
         media_id: u32,
@@ -156,15 +149,12 @@ impl DiskIo2 {
     /// tracking is required.
     ///
     /// # Errors:
-    /// * `uefi::status::INVALID_PARAMETER` The write request contains device addresses
-    ///                                     that are not valid for the device.
-    /// * `uefi::status::OUT_OF_RESOURCES`  The request could not be completed due to
-    ///                                     a lack of resources.
-    /// * `uefi::status::MEDIA_CHANGED`     `media_id` is not for the current medium.
-    /// * `uefi::status::NO_MEDIA`          There is no medium in the device.
-    /// * `uefi::status::DEVICE_ERROR`      The device reported an error while performing
-    ///                                     the write operation.
-    /// * `uefi::status::WRITE_PROTECTED`   The device cannot be written to.
+    /// * [`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.
     pub unsafe fn write_disk_raw(
         &mut self,
         media_id: u32,
@@ -191,14 +181,11 @@ impl DiskIo2 {
     /// * `token` - Transaction token for the asynchronous flush.
     ///
     /// # Errors:
-    /// * `uefi::status::OUT_OF_RESOURCES`  The request could not be completed due to
-    ///                                     a lack of resources.
-    /// * `uefi::status::MEDIA_CHANGED`     The medium in the device has changed since
-    ///                                     the last access.
-    /// * `uefi::status::NO_MEDIA`          There is no medium in the device.
-    /// * `uefi::status::DEVICE_ERROR`      The device reported an error while performing
-    ///                                     the flush operation.
-    /// * `uefi::status::WRITE_PROTECTED`   The device cannot be written to.
+    /// * [`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.
     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()
diff --git a/uefi/src/proto/media/load_file.rs b/uefi/src/proto/media/load_file.rs
@@ -3,6 +3,8 @@
 //! LoadFile and LoadFile2 protocols.
 
 use crate::proto::unsafe_protocol;
+#[cfg(doc)]
+use crate::Status;
 #[cfg(all(feature = "alloc", feature = "unstable"))]
 use alloc::alloc::Global;
 use uefi_raw::protocol::media::{LoadFile2Protocol, LoadFileProtocol};
@@ -44,22 +46,22 @@ impl LoadFile {
     /// - `boot_policy` The [`BootPolicy`] to use.
     ///
     /// # Errors
-    /// - `uefi::status::EFI_SUCCESS` The file was loaded.
-    /// - `uefi::status::EFI_UNSUPPORTED` The device does not support the
+    /// - [`Status::SUCCESS`] The file was loaded.
+    /// - [`Status::UNSUPPORTED`] The device does not support the
     ///   provided BootPolicy.
-    /// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device
+    /// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
     ///   path, or BufferSize is NULL.
-    /// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file.
-    /// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a
+    /// - [`Status::NO_MEDIA`] No medium was present to load the file.
+    /// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
     ///   device error.
-    /// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond.
-    /// - `uefi::status::EFI_NOT_FOUND` The file was not found.
-    /// - `uefi::status::EFI_ABORTED` The file load process was manually
+    /// - [`Status::NO_RESPONSE`] The remote system did not respond.
+    /// - [`Status::NOT_FOUND`] The file was not found.
+    /// - [`Status::ABORTED`] The file load process was manually
     ///   cancelled.
-    /// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to
+    /// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
     ///   read the current directory entry. BufferSize has been updated with the
     ///   size needed to complete the request.
-    /// - `uefi::status::EFI_WARN_FILE_SYSTEM` The resulting Buffer contains
+    /// - [`Status::WARN_FILE_SYSTEM`] The resulting Buffer contains
     ///   UEFI-compliant file system.
     ///
     /// [`BootPolicy`]: uefi::proto::BootPolicy
@@ -119,18 +121,18 @@ impl LoadFile2 {
     /// - `file_path` The device specific path of the file to load.
     ///
     /// # Errors
-    /// - `uefi::status::EFI_SUCCESS` The file was loaded.
-    /// - `uefi::status::EFI_UNSUPPORTED` BootPolicy is TRUE.
-    /// - `uefi::status::EFI_INVALID_PARAMETER` FilePath is not a valid device
+    /// - [`Status::SUCCESS`] The file was loaded.
+    /// - [`Status::UNSUPPORTED`] BootPolicy is TRUE.
+    /// - [`Status::INVALID_PARAMETER`] FilePath is not a valid device
     ///   path, or BufferSize is NULL.
-    /// - `uefi::status::EFI_NO_MEDIA` No medium was present to load the file.
-    /// - `uefi::status::EFI_DEVICE_ERROR` The file was not loaded due to a
+    /// - [`Status::NO_MEDIA`] No medium was present to load the file.
+    /// - [`Status::DEVICE_ERROR`] The file was not loaded due to a
     ///   device error.
-    /// - `uefi::status::EFI_NO_RESPONSE` The remote system did not respond.
-    /// - `uefi::status::EFI_NOT_FOUND` The file was not found.
-    /// - `uefi::status::EFI_ABORTED` The file load process was manually
+    /// - [`Status::NO_RESPONSE`] The remote system did not respond.
+    /// - [`Status::NOT_FOUND`] The file was not found.
+    /// - [`Status::ABORTED`] The file load process was manually
     ///   cancelled.
-    /// - `uefi::status::EFI_BUFFER_TOO_SMALL` The BufferSize is too small to
+    /// - [`Status::BUFFER_TOO_SMALL`] The BufferSize is too small to
     ///   read the current directory entry. BufferSize has been updated with the
     ///   size needed to complete the request.
     #[cfg(feature = "alloc")]
