Miscellaneous documentation cleanups. (#863)

Author: sunfishcode

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 {