Miscellaneous documentation cleanups.

src/backend/libc/c.rs

@@ -329,7 +329,7 @@ mod readwrite_pv64 {
 #[cfg(target_os = "android")]
 pub(super) use readwrite_pv64::{preadv64 as preadv, pwritev64 as pwritev};
 
-// macOS added preadv and pwritev in version 11.0
+// macOS added `preadv` and `pwritev` in version 11.0.
 #[cfg(apple)]
 mod readwrite_pv {
     weakcall! {

src/backend/libc/event/epoll.rs

@@ -312,8 +312,8 @@ pub struct Event {
     pub data: EventData,
 }
 
-/// Data assocated with an [`Event`]. This can either be a 64-bit integer value
-/// or a pointer which preserves pointer provenance.
+/// Data associated with an [`Event`]. This can either be a 64-bit integer
+/// value or a pointer which preserves pointer provenance.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub union EventData {

src/backend/libc/fs/inotify.rs

@@ -38,7 +38,7 @@ bitflags! {
         const CLOSE_NOWRITE = c::IN_CLOSE_NOWRITE;
         /// `IN_CLOSE_WRITE`
         const CLOSE_WRITE = c::IN_CLOSE_WRITE;
-        /// `IN_CREATE `
+        /// `IN_CREATE`
         const CREATE = c::IN_CREATE;
         /// `IN_DELETE`
         const DELETE = c::IN_DELETE;
@@ -105,8 +105,8 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     flags: WatchFlags,
 ) -> io::Result<i32> {
     path.into_with_c_str(|path| {
-        // SAFETY: The fd and path we are passing is guaranteed valid by the type
-        // system.
+        // SAFETY: The fd and path we are passing is guaranteed valid by the
+        // type system.
         unsafe {
             ret_c_int(c::inotify_add_watch(
                 borrowed_fd(inot),

src/backend/libc/fs/syscalls.rs

@@ -839,8 +839,8 @@ pub(crate) fn utimensat(
             ));
         }
 
-        // `setattrlistat` was introduced in 10.13 along with `utimensat`, so if
-        // we don't have `utimensat`, we don't have `setattrlistat` either.
+        // `setattrlistat` was introduced in 10.13 along with `utimensat`, so
+        // if we don't have `utimensat`, we don't have `setattrlistat` either.
         // Emulate it using `fork`, and `fchdir` and [`setattrlist`].
         //
         // [`setattrlist`]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/setattrlist.2.html
@@ -1565,7 +1565,8 @@ pub(crate) fn fallocate(
         assert!(mode.is_empty());
         let err = unsafe { c::posix_fallocate(borrowed_fd(fd), offset, len) };
 
-        // `posix_fallocate` returns its error status rather than using `errno`.
+        // `posix_fallocate` returns its error status rather than using
+        // `errno`.
         if err == 0 {
             Ok(())
         } else {

src/backend/libc/fs/types.rs

@@ -213,9 +213,9 @@ bitflags! {
         /// Similar to `ACCMODE`, but just includes the read/write flags, and
         /// no other flags.
         ///
-        /// Some implementations include `O_PATH` in `O_ACCMODE`, when
+        /// On some platforms, `PATH` may be included in `ACCMODE`, when
         /// sometimes we really just want the read/write bits. Caution is
-        /// indicated, as the presence of `O_PATH` may mean that the read/write
+        /// indicated, as the presence of `PATH` may mean that the read/write
         /// bits don't have their usual meaning.
         const RWMODE = bitcast!(c::O_RDONLY | c::O_WRONLY | c::O_RDWR);
 
@@ -638,13 +638,13 @@ bitflags! {
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct SealFlags: u32 {
-        /// `F_SEAL_SEAL`.
+        /// `F_SEAL_SEAL`
         const SEAL = bitcast!(c::F_SEAL_SEAL);
-        /// `F_SEAL_SHRINK`.
+        /// `F_SEAL_SHRINK`
         const SHRINK = bitcast!(c::F_SEAL_SHRINK);
-        /// `F_SEAL_GROW`.
+        /// `F_SEAL_GROW`
         const GROW = bitcast!(c::F_SEAL_GROW);
-        /// `F_SEAL_WRITE`.
+        /// `F_SEAL_WRITE`
         const WRITE = bitcast!(c::F_SEAL_WRITE);
         /// `F_SEAL_FUTURE_WRITE` (since Linux 5.1)
         #[cfg(linux_kernel)]

src/backend/libc/net/read_sockaddr.rs

@@ -139,9 +139,9 @@ pub(crate) unsafe fn read_sockaddr(
 
                 // Trim off unused bytes from the end of `path_bytes`.
                 let path_bytes = if cfg!(target_os = "freebsd") {
-                    // FreeBSD sometimes sets the length to longer than the length
-                    // of the NUL-terminated string. Find the NUL and truncate the
-                    // string accordingly.
+                    // FreeBSD sometimes sets the length to longer than the
+                    // length of the NUL-terminated string. Find the NUL and
+                    // truncate the string accordingly.
                     &decode.sun_path[..decode
                         .sun_path
                         .iter()

src/backend/libc/net/sockopt.rs

@@ -70,8 +70,7 @@ use alloc::string::String;
 use c::TCP_KEEPALIVE as TCP_KEEPIDLE;
 #[cfg(not(any(apple, target_os = "openbsd", target_os = "haiku", target_os = "nto")))]
 use c::TCP_KEEPIDLE;
-use core::mem::size_of;
-use core::mem::MaybeUninit;
+use core::mem::{size_of, MaybeUninit};
 use core::time::Duration;
 #[cfg(windows)]
 use windows_sys::Win32::Foundation::BOOL;

src/backend/libc/pty/syscalls.rs

@@ -67,7 +67,8 @@ pub(crate) fn ptsname(fd: BorrowedFd<'_>, mut buffer: Vec<u8>) -> io::Result<CSt
             if let Some(libc_ptsname_r) = ptsname_r.get() {
                 libc_ptsname_r(borrowed_fd(fd), buffer.as_mut_ptr().cast(), buffer.len())
             } else {
-                // The size declared in the `TIOCPTYGNAME` macro in sys/ttycom.h is 128.
+                // The size declared in the `TIOCPTYGNAME` macro in
+                // sys/ttycom.h is 128.
                 let mut name: [u8; 128] = [0_u8; 128];
                 match c::ioctl(borrowed_fd(fd), c::TIOCPTYGNAME as _, &mut name) {
                     0 => {
@@ -87,7 +88,8 @@ pub(crate) fn ptsname(fd: BorrowedFd<'_>, mut buffer: Vec<u8>) -> io::Result<CSt
             return Err(io::Errno::from_raw_os_error(r));
         }
 
-        buffer.reserve(1); // use `Vec` reallocation strategy to grow capacity exponentially
+        // Use `Vec` reallocation strategy to grow capacity exponentially.
+        buffer.reserve(1);
         buffer.resize(buffer.capacity(), 0_u8);
     }
 }

src/backend/libc/termios/syscalls.rs

@@ -148,8 +148,8 @@ pub(crate) fn tcsetattr(
         #[cfg(any(target_arch = "sparc", target_arch = "sparc64"))]
         const TCSETS2: u32 = 0x802c540d;
 
-        // Translate from `optional_actions` into an ioctl request code. On MIPS,
-        // `optional_actions` already has `TCGETS` added to it.
+        // Translate from `optional_actions` into an ioctl request code. On
+        // MIPS, `optional_actions` already has `TCGETS` added to it.
         let request = TCSETS2
             + if cfg!(any(
                 target_arch = "mips",

src/backend/linux_raw/event/epoll.rs

@@ -288,8 +288,8 @@ pub struct Event {
     pub data: EventData,
 }
 
-/// Data assocated with an [`Event`]. This can either be a 64-bit integer value
-/// or a pointer which preserves pointer provenance.
+/// Data associated with an [`Event`]. This can either be a 64-bit integer
+/// value or a pointer which preserves pointer provenance.
 #[repr(C)]
 #[derive(Copy, Clone)]
 pub union EventData {

src/backend/linux_raw/fs/inotify.rs

@@ -38,7 +38,7 @@ bitflags! {
         const CLOSE_NOWRITE = linux_raw_sys::general::IN_CLOSE_NOWRITE;
         /// `IN_CLOSE_WRITE`
         const CLOSE_WRITE = linux_raw_sys::general::IN_CLOSE_WRITE;
-        /// `IN_CREATE `
+        /// `IN_CREATE`
         const CREATE = linux_raw_sys::general::IN_CREATE;
         /// `IN_DELETE`
         const DELETE = linux_raw_sys::general::IN_DELETE;

src/backend/linux_raw/fs/types.rs

@@ -179,9 +179,9 @@ bitflags! {
         /// Similar to `ACCMODE`, but just includes the read/write flags, and
         /// no other flags.
         ///
-        /// Some implementations include `O_PATH` in `O_ACCMODE`, when
+        /// On some platforms, `PATH` may be included in `ACCMODE`, when
         /// sometimes we really just want the read/write bits. Caution is
-        /// indicated, as the presence of `O_PATH` may mean that the read/write
+        /// indicated, as the presence of `PATH` may mean that the read/write
         /// bits don't have their usual meaning.
         const RWMODE = linux_raw_sys::general::O_RDONLY |
                        linux_raw_sys::general::O_WRONLY |

src/backend/linux_raw/shm/syscalls.rs

@@ -1,9 +1,7 @@
 use crate::ffi::CStr;
 
-use crate::backend::fs::{
-    syscalls::{open, unlink},
-    types::{Mode, OFlags},
-};
+use crate::backend::fs::syscalls::{open, unlink};
+use crate::backend::fs::types::{Mode, OFlags};
 use crate::fd::OwnedFd;
 use crate::io;
 use crate::shm::ShmOFlags;

src/backend/linux_raw/system/syscalls.rs

@@ -6,13 +6,10 @@
 #![allow(unsafe_code, clippy::undocumented_unsafe_blocks)]
 
 use super::types::RawUname;
-use crate::backend::{
-    c,
-    conv::{c_int, ret, ret_infallible, slice},
-};
+use crate::backend::c;
+use crate::backend::conv::{c_int, ret, ret_infallible, slice};
 use crate::io;
-use crate::system::RebootCommand;
-use crate::system::Sysinfo;
+use crate::system::{RebootCommand, Sysinfo};
 use core::mem::MaybeUninit;
 
 #[inline]

src/backend/linux_raw/vdso.rs

@@ -55,7 +55,7 @@ fn elf_hash(name: &CStr) -> u32 {
 
 /// Create a `Vdso` value by parsing the vDSO at the `sysinfo_ehdr` address.
 fn init_from_sysinfo_ehdr() -> Option<Vdso> {
-    // SAFETY: the auxv initialization code does extensive checks to ensure
+    // SAFETY: The auxv initialization code does extensive checks to ensure
     // that the value we get really is an `AT_SYSINFO_EHDR` value from the
     // kernel.
     unsafe {
@@ -106,9 +106,9 @@ fn init_from_sysinfo_ehdr() -> Option<Vdso> {
                 vdso.load_end = vdso.base_plus(phdr.p_offset.checked_add(phdr.p_memsz)?)?;
                 vdso.pv_offset = phdr.p_offset.wrapping_sub(phdr.p_vaddr);
             } else if phdr.p_type == PT_DYNAMIC {
-                // If `p_offset` is zero, it's more likely that we're looking at memory
-                // that has been zeroed than that the kernel has somehow aliased the
-                // `Ehdr` and the `Elf_Dyn` array.
+                // If `p_offset` is zero, it's more likely that we're looking
+                // at memory that has been zeroed than that the kernel has
+                // somehow aliased the `Ehdr` and the `Elf_Dyn` array.
                 if phdr.p_offset < size_of::<Elf_Ehdr>() {
                     return None;
                 }
@@ -117,9 +117,9 @@ fn init_from_sysinfo_ehdr() -> Option<Vdso> {
                     .as_ptr();
                 num_dyn = phdr.p_memsz / size_of::<Elf_Dyn>();
             } else if phdr.p_type == PT_INTERP || phdr.p_type == PT_GNU_RELRO {
-                // Don't trust any ELF image that has an “interpreter” or that uses
-                // RELRO, which is likely to be a user ELF image rather and not the
-                // kernel vDSO.
+                // Don't trust any ELF image that has an “interpreter” or
+                // that uses RELRO, which is likely to be a user ELF image
+                // rather and not the kernel vDSO.
                 return None;
             }
         }
@@ -176,8 +176,8 @@ fn init_from_sysinfo_ehdr() -> Option<Vdso> {
             }
             i = i.checked_add(1)?;
         }
-        // The upstream code checks `symstrings`, `symtab`, and `hash` for null;
-        // here, `check_raw_pointer` has already done that.
+        // The upstream code checks `symstrings`, `symtab`, and `hash` for
+        // null; here, `check_raw_pointer` has already done that.
 
         if vdso.verdef.is_null() {
             vdso.versym = null();

src/backend/linux_raw/vdso_wrappers.rs

@@ -36,8 +36,8 @@ use {
 #[inline]
 pub(crate) fn clock_gettime(which_clock: ClockId) -> __kernel_timespec {
     // SAFETY: `CLOCK_GETTIME` contains either null or the address of a
-    // function with an ABI like libc `clock_gettime`, and calling it has
-    // the side effect of writing to the result buffer, and no others.
+    // function with an ABI like libc `clock_gettime`, and calling it has the
+    // side effect of writing to the result buffer, and no others.
     unsafe {
         let mut result = MaybeUninit::<__kernel_timespec>::uninit();
         let callee = match transmute(CLOCK_GETTIME.load(Relaxed)) {
@@ -78,8 +78,8 @@ pub(crate) fn clock_gettime_dynamic(which_clock: DynamicClockId<'_>) -> io::Resu
     };
 
     // SAFETY: `CLOCK_GETTIME` contains either null or the address of a
-    // function with an ABI like libc `clock_gettime`, and calling it has
-    // the side effect of writing to the result buffer, and no others.
+    // function with an ABI like libc `clock_gettime`, and calling it has the
+    // side effect of writing to the result buffer, and no others.
     unsafe {
         const EINVAL: c::c_int = -(c::EINVAL as c::c_int);
         let mut timespec = MaybeUninit::<Timespec>::uninit();
@@ -234,8 +234,8 @@ pub(super) type SyscallType = unsafe extern "C" fn();
 #[cold]
 fn init_clock_gettime() -> ClockGettimeType {
     init();
-    // SAFETY: Load the function address from static storage that we
-    // just initialized.
+    // SAFETY: Load the function address from static storage that we just
+    // initialized.
     unsafe { transmute(CLOCK_GETTIME.load(Relaxed)) }
 }
 
@@ -244,8 +244,8 @@ fn init_clock_gettime() -> ClockGettimeType {
 #[cold]
 fn init_syscall() -> SyscallType {
     init();
-    // SAFETY: Load the function address from static storage that we
-    // just initialized.
+    // SAFETY: Load the function address from static storage that we just
+    // initialized.
     unsafe { transmute(SYSCALL.load(Relaxed)) }
 }
 
@@ -345,9 +345,9 @@ rustix_int_0x80:
 
 fn minimal_init() {
     // SAFETY: Store default function addresses in static storage so that if we
-    // end up making any system calls while we read the vDSO, they'll work.
-    // If the memory happens to already be initialized, this is redundant, but
-    // not harmful.
+    // end up making any system calls while we read the vDSO, they'll work. If
+    // the memory happens to already be initialized, this is redundant, but not
+    // harmful.
     unsafe {
         #[cfg(feature = "time")]
         {
@@ -381,9 +381,9 @@ fn init() {
     if let Some(vdso) = vdso::Vdso::new() {
         #[cfg(feature = "time")]
         {
-            // Look up the platform-specific `clock_gettime` symbol as documented
-            // [here], except on 32-bit platforms where we look up the
-            // `64`-suffixed variant and fail if we don't find it.
+            // Look up the platform-specific `clock_gettime` symbol as
+            // documented [here], except on 32-bit platforms where we look up
+            // the `64`-suffixed variant and fail if we don't find it.
             //
             // [here]: https://man7.org/linux/man-pages/man7/vdso.7.html
             #[cfg(target_arch = "x86_64")]
@@ -408,8 +408,8 @@ fn init() {
             #[cfg(target_pointer_width = "64")]
             let ok = true;
 
-            // On some 32-bit platforms, the 64-bit `clock_gettime` symbols are not
-            // available on older kernel versions.
+            // On some 32-bit platforms, the 64-bit `clock_gettime` symbols are
+            // not available on older kernel versions.
             #[cfg(any(
                 target_arch = "arm",
                 target_arch = "mips",
@@ -421,9 +421,9 @@ fn init() {
             if ok {
                 assert!(!ptr.is_null());
 
-                // SAFETY: Store the computed function addresses in static storage
-                // so that we don't need to compute it again (but if we do, it
-                // doesn't hurt anything).
+                // SAFETY: Store the computed function addresses in static
+                // storage so that we don't need to compute it again (but if
+                // we do, it doesn't hurt anything).
                 unsafe {
                     CLOCK_GETTIME.store(ptr.cast(), Relaxed);
                 }

src/cstr.rs

@@ -44,8 +44,9 @@ macro_rules! cstr {
             // call `from_bytes_with_nul_unchecked`, which as of this writing
             // is defined as `#[inline]` and completely optimizes away.
             //
-            // SAFETY: We have manually checked that the string does not contain
-            // embedded NULs above, and we append or own NUL terminator here.
+            // SAFETY: We have manually checked that the string does not
+            // contain embedded NULs above, and we append or own NUL terminator
+            // here.
             unsafe {
                 $crate::ffi::CStr::from_bytes_with_nul_unchecked(concat!($str, "\0").as_bytes())
             }

src/fs/abs.rs

@@ -129,7 +129,8 @@ fn _readlink(path: &CStr, mut buffer: Vec<u8>) -> io::Result<CString> {
             buffer.resize(nread, 0_u8);
             return Ok(CString::new(buffer).unwrap());
         }
-        buffer.reserve(1); // use `Vec` reallocation strategy to grow capacity exponentially
+        // Use `Vec` reallocation strategy to grow capacity exponentially.
+        buffer.reserve(1);
         buffer.resize(buffer.capacity(), 0_u8);
     }
 }

src/fs/at.rs

@@ -104,8 +104,8 @@ fn _readlinkat(dirfd: BorrowedFd<'_>, path: &CStr, mut buffer: Vec<u8>) -> io::R
 
         debug_assert!(nread <= buffer.capacity());
         if nread < buffer.capacity() {
-            // SAFETY: From the [documentation]:
-            // "On success, these calls return the number of bytes placed in buf."
+            // SAFETY: From the [documentation]: "On success, these calls
+            // return the number of bytes placed in buf."
             //
             // [documentation]: https://man7.org/linux/man-pages/man2/readlinkat.2.html
             unsafe {

src/fs/fd.rs

@@ -107,8 +107,8 @@ pub fn tell<Fd: AsFd>(fd: Fd) -> io::Result<u64> {
 
 /// `fchmod(fd, mode)`—Sets open file or directory permissions.
 ///
-/// This implementation does not support `O_PATH` file descriptors, even on
-/// platforms where the host libc emulates it.
+/// This implementation does not support [`OFlags::PATH`] file descriptors,
+/// even on platforms where the host libc emulates it.
 ///
 /// # References
 ///  - [POSIX]