fs protocol: improved doc of read function

Author: phip1611

src/proto/media/file/dir.rs

@@ -20,25 +20,17 @@ impl Directory {
         Self(RegularFile::new(handle))
     }
 
-    /// Read the next directory entry
+    /// Read the next directory entry.
     ///
-    /// Try to read the next directory entry into `buffer`. If the buffer is too small, report the
-    /// required buffer size as part of the error. If there are no more directory entries, return
-    /// an empty optional.
-    ///
-    /// The input buffer must be correctly aligned for a `FileInfo`. You can query the required
-    /// alignment through the `Align` trait (`<FileInfo as Align>::alignment()`).
+    /// Under the hood, this wraps [`super::RegularFile::read`]. Please refer to it's documentation.
     ///
     /// # Arguments
     /// * `buffer`  The target buffer of the read operation
     ///
-    /// # Errors
-    /// * `uefi::Status::NO_MEDIA`           The device has no media
-    /// * `uefi::Status::DEVICE_ERROR`       The device reported an error, the file was deleted,
-    ///                                      or the end of the file was reached before the `read()`.
-    /// * `uefi::Status::VOLUME_CORRUPTED`   The filesystem structures are corrupted
-    /// * `uefi::Status::BUFFER_TOO_SMALL`   The buffer is too small to hold a directory entry,
-    ///                                      the required buffer size is provided into the error.
+    /// # Return Value
+    /// This method returns a UEFI [`Result`]. In the success case, this method returns an `Option`
+    /// with the file info (`None` if the directory contains no more entries) or, in the error case,
+    /// the required buffer size, if the provided buffer was too small.
     pub fn read_entry<'buf>(
         &mut self,
         buffer: &'buf mut [u8],
@@ -47,8 +39,9 @@ impl Directory {
         FileInfo::assert_aligned(buffer);
 
         // Read the directory entry into the aligned storage
-        self.0.read(buffer).map(|size| {
-            if size != 0 {
+        self.0.read(buffer).map(|read_bytes| {
+            // 0 signalizes that the last directory entry was read
+            if read_bytes != 0 {
                 unsafe { Some(FileInfo::from_uefi(buffer.as_mut_ptr().cast::<c_void>())) }
             } else {
                 None

src/proto/media/file/regular.rs

@@ -21,15 +21,32 @@ impl RegularFile {
         Self(handle)
     }
 
-    /// Read data from file
+    /// Read data from a file, hence, a regular file or a directory.
     ///
-    /// Try to read as much as possible into `buffer`. Returns the number of bytes that were
-    /// actually read.
+    /// # Read from Regular Files
+    /// If `self` is not a directory, the function reads the requested number of bytes from the file
+    /// at the file’s current position and returns them in `buffer`. If the read goes beyond the end
+    /// of the file, the read length is truncated to the end of the file. The file’s current
+    /// position is increased by the number of bytes returned.
+    ///
+    /// # Read from Directory
+    /// If `self` is a directory, the function reads the directory entry at the file’s current
+    /// position and returns the entry in `buffer`. If the `buffer` is not large enough to hold the
+    /// current directory entry, then `EFI_BUFFER_TOO_SMALL` is returned and the current file
+    /// position is not updated. `buffer_size` is set to be the size of the buffer needed to read
+    /// the entry. On success, the current position is updated to the next directory entry. If there
+    /// are no more directory entries, the read returns a zero-length buffer. `EFI_FILE_INFO` is the
+    /// structure returned as the directory entry.
     ///
     /// # Arguments
     /// * `buffer`  The target buffer of the read operation
     ///
-    /// # Errors
+    /// # Return Value
+    /// This method returns a UEFI [`Result`]. In the success case, this method returns the number
+    /// of read bytes (0 is EOF) or, in the error case, with the required buffer size, if the
+    /// provided buffer was too small.
+    ///
+    /// ## Status Error Codes
     /// * `uefi::Status::NO_MEDIA`           The device has no media
     /// * `uefi::Status::DEVICE_ERROR`       The device reported an error, the file was deleted,
     ///                                      or the end of the file was reached before the `read()`.
@@ -38,10 +55,16 @@ impl RegularFile {
     ///                                      and the required buffer size is provided as output.
     pub fn read(&mut self, buffer: &mut [u8]) -> Result<usize, Option<usize>> {
         let mut buffer_size = buffer.len();
-        unsafe { (self.imp().read)(self.imp(), &mut buffer_size, buffer.as_mut_ptr()) }.into_with(
+        let status =
+            unsafe { (self.imp().read)(self.imp(), &mut buffer_size, buffer.as_mut_ptr()) };
+
+        // Now, buffer_size is updated. It either contains the number of read bytes or the number
+        // of required bytes to read the whole entry.
+        status.into_with(
             || buffer_size,
-            |s| {
+            |s: Status| {
                 if s == Status::BUFFER_TOO_SMALL {
+                    // This was updated to the required buffer size.
                     Some(buffer_size)
                 } else {
                     None

src/result/status.rs

@@ -123,6 +123,9 @@ impl Status {
     }
 
     /// Converts this status code into a result with a given value.
+    ///
+    /// The status representing the specific error code is embedded into the error value of
+    /// the [`Result`].
     #[inline]
     pub fn into_with_val<T>(self, val: impl FnOnce() -> T) -> Result<T, ()> {
         if self.is_success() {
@@ -132,7 +135,10 @@ impl Status {
         }
     }
 
-    /// Converts this status code into a result with a given error payload
+    /// Converts this status code into a result with a given error payload.
+    ///
+    /// The status representing the specific error code is embedded into the error value of
+    /// the [`Result`].
     #[inline]
     pub fn into_with_err<ErrData: Debug>(
         self,
@@ -145,7 +151,10 @@ impl Status {
         }
     }
 
-    /// Convert this status code into a result with a given value and error payload
+    /// Convert this status code into a result with a given value and error payload.
+    ///
+    /// The status representing the specific error code is embedded into the error value of
+    /// the [`Result`].
     #[inline]
     pub fn into_with<T, ErrData: Debug>(
         self,