Miscellaneous documentaion cleanups. (#1365)

Author: sunfishcode

ci/select-setsize.patch

@@ -2,7 +2,7 @@ From Dan Gohman <[email protected]>
 Subject: [PATCH] Remove the `FD_SETSIZE` limitation in `select`
 
 The `fd_set` type is limited to a fixed `FD_SETSIZE` number of file
-descriptors, however Linux's `select has no such limitation. Change
+descriptors, however Linux's `select` has no such limitation. Change
 the `select` implementation to using manual bit-vector logic to better
 implement the Linux semantics.
 

examples/kq.rs

@@ -41,15 +41,15 @@ fn main() -> std::io::Result<()> {
         Event::new(
             EventFilter::Timer {
                 ident: 0,
-                timer: Some(core::time::Duration::from_secs(1)),
+                timer: Some(std::time::Duration::from_secs(1)),
             },
             EventFlags::ADD,
             null_mut(),
         ),
         Event::new(
             EventFilter::Timer {
                 ident: 1,
-                timer: Some(core::time::Duration::from_secs(2)),
+                timer: Some(std::time::Duration::from_secs(2)),
             },
             EventFlags::ADD | EventFlags::ONESHOT,
             null_mut(),

examples/process.rs

@@ -1,6 +1,6 @@
 //! A command which prints out information about the process it runs in.
 
-#[cfg(all(feature = "process", feature = "param"))]
+#[cfg(all(feature = "process", feature = "param", feature = "system"))]
 #[cfg(not(windows))]
 fn main() -> rustix::io::Result<()> {
     #[cfg(not(target_os = "espidf"))]
@@ -88,7 +88,10 @@ fn main() -> rustix::io::Result<()> {
     Ok(())
 }
 
-#[cfg(any(windows, not(all(feature = "process", feature = "param"))))]
+#[cfg(any(
+    windows,
+    not(all(feature = "process", feature = "param", feature = "system"))
+))]
 fn main() -> Result<(), &'static str> {
-    Err("This example requires --features=process,param and is not supported on Windows.")
+    Err("This example requires --features=process,param,system and is not supported on Windows.")
 }

src/backend/libc/event/syscalls.rs

@@ -35,24 +35,19 @@ use core::mem::MaybeUninit;
 use core::ptr::null;
 #[cfg(any(bsd, linux_kernel, solarish, target_os = "redox", target_os = "wasi"))]
 use core::ptr::null_mut;
-#[cfg(any(
-    linux_kernel,
-    solarish,
-    target_os = "redox",
-    all(feature = "alloc", bsd)
-))]
+#[cfg(any(bsd, linux_kernel, solarish, target_os = "redox"))]
 use {crate::backend::conv::borrowed_fd, crate::fd::BorrowedFd};
 #[cfg(any(
+    bsd,
     linux_kernel,
     solarish,
     target_os = "freebsd",
     target_os = "illumos",
     target_os = "espidf",
-    target_os = "redox",
-    all(feature = "alloc", bsd)
+    target_os = "redox"
 ))]
 use {crate::backend::conv::ret_owned_fd, crate::fd::OwnedFd};
-#[cfg(all(feature = "alloc", bsd))]
+#[cfg(bsd)]
 use {crate::event::kqueue::Event, crate::utils::as_ptr};
 
 #[cfg(any(
@@ -91,12 +86,12 @@ pub(crate) fn eventfd(initval: u32, flags: EventfdFlags) -> io::Result<OwnedFd>
     }
 }
 
-#[cfg(all(feature = "alloc", bsd))]
+#[cfg(bsd)]
 pub(crate) fn kqueue() -> io::Result<OwnedFd> {
     unsafe { ret_owned_fd(c::kqueue()) }
 }
 
-#[cfg(all(feature = "alloc", bsd))]
+#[cfg(bsd)]
 pub(crate) unsafe fn kevent(
     kq: BorrowedFd<'_>,
     changelist: &[Event],

src/backend/libc/net/read_sockaddr.rs

@@ -127,8 +127,8 @@ pub(crate) unsafe fn sockaddr_nonempty(storage: *const c::sockaddr, len: SocketA
         return false;
     }
 
-    // On macOS, if we get an `AF_UNIX` with an empty path, treat it as
-    // an absent address.
+    // On macOS, if we get an `AF_UNIX` with an empty path, treat it as an
+    // absent address.
     #[cfg(apple)]
     if family == c::AF_UNIX && read_sun_path0(storage) == 0 {
         return false;

src/backend/libc/termios/types.rs

@@ -5,9 +5,9 @@
 #[cfg(not(target_os = "redox"))]
 use crate::ffi;
 
-// We don't want to use tcflag_t directly so we don't expose libc
-// publicly. Redox uses u32, apple uses c_ulong, everything else
-// seems to use c_uint.
+// We don't want to use `tcflag_t` directly so we don't expose libc
+// publicly. Redox uses `u32`, apple uses `c_ulong`, everything else
+// seems to use `c_uint`.
 
 #[cfg(apple)]
 pub type tcflag_t = ffi::c_ulong;

src/backend/libc/winsock_c.rs

@@ -21,8 +21,8 @@ pub(crate) type c_long = i32;
 pub(crate) type c_ulong = u32;
 pub(crate) use core::ffi::c_void;
 
-// windows-sys declares these constants as u16. For better compatibility
-// with Unix-family APIs, redeclare them as u32.
+// windows-sys declares these constants as `u16`. For better compatibility with
+// Unix-family APIs, redeclare them as `i32`.
 pub(crate) const AF_INET: i32 = WinSock::AF_INET as _;
 pub(crate) const AF_INET6: i32 = WinSock::AF_INET6 as _;
 pub(crate) const AF_UNSPEC: i32 = WinSock::AF_UNSPEC as _;

src/backend/linux_raw/fs/dir.rs

@@ -176,7 +176,7 @@ impl Dir {
         let name = name.to_owned();
         assert!(name.as_bytes().len() <= self.buf.len() - name_start);
 
-        // Do an unaligned u64 load for `d_ino`.
+        // Do an unaligned `u64` load for `d_ino`.
         let d_ino = u64::from_ne_bytes([
             self.buf[pos + offsetof_d_ino],
             self.buf[pos + offsetof_d_ino + 1],
@@ -188,7 +188,7 @@ impl Dir {
             self.buf[pos + offsetof_d_ino + 7],
         ]);
 
-        // Do an unaligned i64 load for `d_off`
+        // Do an unaligned `i64` load for `d_off`.
         let d_off = i64::from_ne_bytes([
             self.buf[pos + offsetof_d_off],
             self.buf[pos + offsetof_d_off + 1],

src/backend/linux_raw/mm/syscalls.rs

@@ -226,8 +226,9 @@ pub(crate) fn mlockall(flags: MlockAllFlags) -> io::Result<()> {
     // because if a load happens and evokes a fault before the `mlockall`,
     // the memory doesn't get locked, but if the load and therefore
     // the fault happens after, then the memory does get locked.
-    // So to be conservative in this regard, we use `syscall` instead
-    // of `syscall_readonly`
+    //
+    // So to be conservative in this regard, we use `syscall` instead of
+    // `syscall_readonly`
     unsafe { ret(syscall!(__NR_mlockall, flags)) }
 }
 

src/buffer.rs

@@ -12,8 +12,8 @@ use core::slice;
 /// There are three types that implement the `Buffer` trait, and the type you
 /// use determines the return type of the functions that use it:
 ///
-/// | If you pass a...         | You get back a... |
-/// | ------------------------ | ----------------- |
+/// | If you pass a…           | You get back a… |
+/// | ------------------------ | --------------- |
 /// | `&mut [u8]`              | `usize`, indicating the number of elements initialized. |
 /// | `&mut [MaybeUninit<u8>]` | `(&mut [u8], &[mut MaybeUninit<u8>])`, holding the initialized and uninitialized subslices. |
 /// | [`SpareCapacity`]        | `usize`, indicating the number of elements initialized. And the `Vec` is extended. |
@@ -35,7 +35,7 @@ use core::slice;
 ///
 /// ```rust
 /// # use rustix::io::read;
-/// # use core::mem::MaybeUninit;
+/// # use std::mem::MaybeUninit;
 /// # fn example(fd: rustix::fd::BorrowedFd) -> rustix::io::Result<()> {
 /// let mut buf = [MaybeUninit::<u8>::uninit(); 64];
 /// let (init, uninit) = read(fd, &mut buf)?;
@@ -67,26 +67,26 @@ use core::slice;
 /// "cannot move out of `self` which is behind a mutable reference"
 /// and
 /// "move occurs because `x` has type `&mut [u8]`, which does not implement the `Copy` trait",
-/// replace `x` with `&mut *x`. See `confusing_error_buffer_wrapper` in
+/// replace `x` with `&mut *x`. See `error_buffer_wrapper` in
 /// examples/buffer_errors.rs.
 ///
 /// If you see errors like
 /// "type annotations needed"
 /// and
 /// "cannot infer type of the type parameter `Buf` declared on the function `read`",
 /// you may need to change a `&mut []` to `&mut [0_u8; 0]`. See
-/// `confusing_error_empty_slice` in examples/buffer_errors.rs.
+/// `error_empty_slice` in examples/buffer_errors.rs.
 ///
 /// If you see errors like
 /// "the trait bound `[MaybeUninit<u8>; 1]: Buffer<u8>` is not satisfied",
 /// add a `&mut` to pass the array by reference instead of by value. See
-/// `confusing_error_array_by_value` in examples/buffer_errors.rs.
+/// `error_array_by_value` in examples/buffer_errors.rs.
 ///
 /// If you see errors like
 /// "cannot move out of `x`, a captured variable in an `FnMut` closure",
-/// try replacing `x` with `&mut *x`, or, if that doesn't work, try moving
-/// a `let` into the closure body. See `confusing_error_retry_closure` and
-/// `confusing_error_retry_indirect_closure` in examples/buffer_errors.rs.
+/// try replacing `x` with `&mut *x`, or, if that doesn't work, try moving a
+/// `let` into the closure body. See `error_retry_closure` and
+/// `error_retry_indirect_closure` in examples/buffer_errors.rs.
 pub trait Buffer<T>: private::Sealed<T> {}
 
 // Implement `Buffer` for all the types that implement `Sealed`.
@@ -219,8 +219,8 @@ pub struct SpareCapacity<'a, T>(&'a mut Vec<T>);
 /// Construct an [`SpareCapacity`], which implements [`Buffer`].
 ///
 /// This wraps a `Vec` and uses the spare capacity of the `Vec` as the buffer
-/// to receive data in, automatically setting the length of the `Vec` to
-/// include the received elements.
+/// to receive data in, automatically calling `set_len` on the `Vec` to set the
+/// length to include the received elements.
 ///
 /// This uses the existing capacity, and never allocates, so the `Vec` should
 /// have some non-empty spare capacity!
@@ -285,6 +285,12 @@ mod private {
         type Output;
 
         /// Return a pointer and length for this buffer.
+        ///
+        /// It's tempting to have this return `&mut [MaybeUninit<T>]` instead,
+        /// however that would require this function to be `unsafe`, because
+        /// callers could use the `&mut [MaybeUninit<T>]` slice to set elements
+        /// to `MaybeUninit::<T>::uninit()`, which would be a problem if `Self`
+        /// is `&mut [T]` or similar.
         fn parts_mut(&mut self) -> (*mut T, usize);
 
         /// Convert a finished buffer pointer into its result.