@@ -12,8 +12,8 @@ use core::slice;
1212/// There are three types that implement the `Buffer` trait, and the type you
1313/// use determines the return type of the functions that use it:
1414///
15- /// | If you pass a... | You get back a... |
16- /// | ------------------------ | ----------------- |
15+ /// | If you pass a… | You get back a… |
16+ /// | ------------------------ | --------------- |
1717/// | `&mut [u8]` | `usize`, indicating the number of elements initialized. |
1818/// | `&mut [MaybeUninit<u8>]` | `(&mut [u8], &[mut MaybeUninit<u8>])`, holding the initialized and uninitialized subslices. |
1919/// | [`SpareCapacity`] | `usize`, indicating the number of elements initialized. And the `Vec` is extended. |
@@ -35,7 +35,7 @@ use core::slice;
3535///
3636/// ```rust
3737/// # use rustix::io::read;
38- /// # use core ::mem::MaybeUninit;
38+ /// # use std ::mem::MaybeUninit;
3939/// # fn example(fd: rustix::fd::BorrowedFd) -> rustix::io::Result<()> {
4040/// let mut buf = [MaybeUninit::<u8>::uninit(); 64];
4141/// let (init, uninit) = read(fd, &mut buf)?;
@@ -67,26 +67,26 @@ use core::slice;
6767/// "cannot move out of `self` which is behind a mutable reference"
6868/// and
6969/// "move occurs because `x` has type `&mut [u8]`, which does not implement the `Copy` trait",
70- /// replace `x` with `&mut *x`. See `confusing_error_buffer_wrapper ` in
70+ /// replace `x` with `&mut *x`. See `error_buffer_wrapper ` in
7171/// examples/buffer_errors.rs.
7272///
7373/// If you see errors like
7474/// "type annotations needed"
7575/// and
7676/// "cannot infer type of the type parameter `Buf` declared on the function `read`",
7777/// you may need to change a `&mut []` to `&mut [0_u8; 0]`. See
78- /// `confusing_error_empty_slice ` in examples/buffer_errors.rs.
78+ /// `error_empty_slice ` in examples/buffer_errors.rs.
7979///
8080/// If you see errors like
8181/// "the trait bound `[MaybeUninit<u8>; 1]: Buffer<u8>` is not satisfied",
8282/// add a `&mut` to pass the array by reference instead of by value. See
83- /// `confusing_error_array_by_value ` in examples/buffer_errors.rs.
83+ /// `error_array_by_value ` in examples/buffer_errors.rs.
8484///
8585/// If you see errors like
8686/// "cannot move out of `x`, a captured variable in an `FnMut` closure",
87- /// try replacing `x` with `&mut *x`, or, if that doesn't work, try moving
88- /// a `let` into the closure body. See `confusing_error_retry_closure ` and
89- /// `confusing_error_retry_indirect_closure ` in examples/buffer_errors.rs.
87+ /// try replacing `x` with `&mut *x`, or, if that doesn't work, try moving a
88+ /// `let` into the closure body. See `error_retry_closure ` and
89+ /// `error_retry_indirect_closure ` in examples/buffer_errors.rs.
9090pub trait Buffer < T > : private:: Sealed < T > { }
9191
9292// Implement `Buffer` for all the types that implement `Sealed`.
@@ -219,8 +219,8 @@ pub struct SpareCapacity<'a, T>(&'a mut Vec<T>);
219219/// Construct an [`SpareCapacity`], which implements [`Buffer`].
220220///
221221/// This wraps a `Vec` and uses the spare capacity of the `Vec` as the buffer
222- /// to receive data in, automatically setting the length of the `Vec` to
223- /// include the received elements.
222+ /// to receive data in, automatically calling `set_len` on the `Vec` to set the
223+ /// length to include the received elements.
224224///
225225/// This uses the existing capacity, and never allocates, so the `Vec` should
226226/// have some non-empty spare capacity!
@@ -285,6 +285,12 @@ mod private {
285285type Output ;
286286
287287 /// Return a pointer and length for this buffer.
288+ ///
289+ /// It's tempting to have this return `&mut [MaybeUninit<T>]` instead,
290+ /// however that would require this function to be `unsafe`, because
291+ /// callers could use the `&mut [MaybeUninit<T>]` slice to set elements
292+ /// to `MaybeUninit::<T>::uninit()`, which would be a problem if `Self`
293+ /// is `&mut [T]` or similar.
288294fn parts_mut ( & mut self ) -> ( * mut T , usize ) ;
289295
290296 /// Convert a finished buffer pointer into its result.
0 commit comments