diff --git a/crates/bevy_asset/src/io/mod.rs b/crates/bevy_asset/src/io/mod.rs index d328f0e214feeb..e5d3a0de0d546a 100644 --- a/crates/bevy_asset/src/io/mod.rs +++ b/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 AsyncSeekForward for Box { /// 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 {