fix and improve docs of AsyncSeekForward

Author: ldubos

crates/bevy_asset/src/io/mod.rs

@@ -83,23 +83,25 @@ pub use stackfuture::StackFuture;
 
 /// Asynchronously advances the cursor position by a specified number of bytes.
 ///
-/// This trait is similar to the `futures_io::AsyncSeek` trait, but it only supports
-/// the `SeekFrom::Current` variant, allowing for relative seeking from the current cursor position.
+/// This trait is a simplified version of the [`futures_io::AsyncSeek`] trait, providing
+/// support exclusively for the [`futures_io::SeekFrom::Current`] variant. It allows for relative
+/// seeking from the current cursor position.
 pub trait AsyncSeekForward {
-    /// Attempt to seek to an offset, in bytes, in a stream from the current cursor position.
+    /// Attempts to asynchronously seek forward by a specified number of bytes from the current cursor position.
     ///
-    /// A seek beyond the end of a stream is allowed, but behavior is defined
-    /// by the implementation.
+    /// Seeking beyond the end of the stream is allowed and the behavior for this case is defined by the implementation.
+    /// The new position, relative to the beginning of the stream, should be returned upon successful completion
+    /// of the seek operation.
     ///
-    /// If the seek operation completed successfully,
-    /// this method returns the new position from the start of the stream.
+    /// If the seek operation completes successfully,
+    /// the new position relative to the beginning of the stream should be returned.
     ///
     /// # Implementation
     ///
-    /// This function may not return errors of kind `WouldBlock` or
-    /// `Interrupted`.  Implementations must convert `WouldBlock` into
-    /// `Poll::Pending` and either internally retry or convert
-    /// `Interrupted` into another error kind.
+    /// Implementations of this trait should handle [`Poll::Pending`] correctly, converting
+    /// [`std::io::ErrorKind::WouldBlock`] errors into [`Poll::Pending`] to indicate that the operation is not
+    /// yet complete and should be retried, and either internally retry or convert
+    /// [`std::io::ErrorKind::Interrupted`] into another error kind.
     fn poll_seek_forward(
         self: Pin<&mut Self>,
         cx: &mut Context<'_>,
@@ -120,7 +122,7 @@ impl<T: ?Sized + AsyncSeekForward + Unpin> AsyncSeekForward for Box<T> {
 /// A type returned from [`AssetReader::read`], which is used to read the contents of a file
 /// (or virtual file) corresponding to an asset.
 ///
-/// This is essentially a trait alias for types implementing  [`AsyncRead`] and [`AsyncForwardSeek`].
+/// This is essentially a trait alias for types implementing [`AsyncRead`] and [`AsyncSeekForward`].
 /// The only reason a blanket implementation is not provided for applicable types is to allow
 /// implementors to override the provided implementation of [`Reader::read_to_end`].
 pub trait Reader: AsyncRead + AsyncSeekForward + Unpin + Send + Sync {