Miscellaneous documentation cleanups. (#887)

sunfishcode · web-flow · commit ce11b6c8cf59 · 2023-10-19T05:56:51.000-07:00
diff --git a/src/backend/libc/fs/inotify.rs b/src/backend/libc/fs/inotify.rs
@@ -90,15 +90,14 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
     unsafe { ret_owned_fd(c::inotify_init1(bitflags_bits!(flags))) }
 }
 
-/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify
+/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify.
 ///
-/// This registers or updates a watch for the filesystem path `path`
-/// and returns a watch descriptor corresponding to this watch.
+/// This registers or updates a watch for the filesystem path `path` and
+/// returns a watch descriptor corresponding to this watch.
 ///
-/// Note: Due to the existence of hardlinks, providing two
-/// different paths to this method may result in it returning
-/// the same watch descriptor. An application should keep track of this
-/// externally to avoid logic errors.
+/// Note: Due to the existence of hardlinks, providing two different paths to
+/// this method may result in it returning the same watch descriptor. An
+/// application should keep track of this externally to avoid logic errors.
 pub fn inotify_add_watch<P: crate::path::Arg>(
     inot: BorrowedFd<'_>,
     path: P,
@@ -117,7 +116,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     })
 }
 
-/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify
+/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify.
 ///
 /// The watch descriptor provided should have previously been returned by
 /// [`inotify_add_watch`] and not previously have been removed.
diff --git a/src/backend/libc/mm/syscalls.rs b/src/backend/libc/mm/syscalls.rs
@@ -225,7 +225,7 @@ pub(crate) unsafe fn userfaultfd(flags: UserfaultfdFlags) -> io::Result<OwnedFd>
 
 /// Locks all pages mapped into the address space of the calling process.
 ///
-/// This includes the pages of the code, data and stack segment, as well as
+/// This includes the pages of the code, data, and stack segment, as well as
 /// shared libraries, user space kernel data, shared memory, and memory-mapped
 /// files. All mapped pages are guaranteed to be resident in RAM when the call
 /// returns successfully; the pages are guaranteed to stay in RAM until later
diff --git a/src/backend/libc/mm/types.rs b/src/backend/libc/mm/types.rs
@@ -453,14 +453,13 @@ bitflags! {
     pub struct MlockAllFlags: u32 {
         // libc doesn't define `MCL_ONFAULT` yet.
         // const ONFAULT = libc::MCL_ONFAULT;
-        /// Lock all pages which will become mapped into the address
-        /// space of the process in the future.  These could be, for
-        /// instance, new pages required by a growing heap and stack
-        /// as well as new memory-mapped files or shared memory
-        /// regions.
+        /// Lock all pages which will become mapped into the address space of
+        /// the process in the future. These could be, for instance, new pages
+        /// required by a growing heap and stack as well as new memory-mapped
+        /// files or shared memory regions.
         const FUTURE = bitcast!(libc::MCL_FUTURE);
-        /// Lock all pages which are currently mapped into the address
-        /// space of the process.
+        /// Lock all pages which are currently mapped into the address space of
+        /// the process.
         const CURRENT = bitcast!(libc::MCL_CURRENT);
 
         /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
diff --git a/src/backend/linux_raw/fs/inotify.rs b/src/backend/linux_raw/fs/inotify.rs
@@ -92,13 +92,12 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
 
 /// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify.
 ///
-/// This registers or updates a watch for the filesystem path `path`
-/// and returns a watch descriptor corresponding to this watch.
+/// This registers or updates a watch for the filesystem path `path` and
+/// returns a watch descriptor corresponding to this watch.
 ///
-/// Note: Due to the existence of hardlinks, providing two
-/// different paths to this method may result in it returning
-/// the same watch descriptor. An application should keep track of this
-/// externally to avoid logic errors.
+/// Note: Due to the existence of hardlinks, providing two different paths to
+/// this method may result in it returning the same watch descriptor. An
+/// application should keep track of this externally to avoid logic errors.
 #[inline]
 pub fn inotify_add_watch<P: crate::path::Arg>(
     inot: BorrowedFd<'_>,
diff --git a/src/backend/linux_raw/io/errno.rs b/src/backend/linux_raw/io/errno.rs
@@ -60,7 +60,7 @@ impl Errno {
     #[inline]
     pub fn from_io_error(io_err: &std::io::Error) -> Option<Self> {
         io_err.raw_os_error().and_then(|raw| {
-            // `std::io::Error` could theoretically have arbitrary "OS error"
+            // `std::io::Error` could theoretically have arbitrary OS error
             // values, so check that they're in Linux's range.
             if (1..4096).contains(&raw) {
                 Some(Self::from_errno(raw as u32))
diff --git a/src/backend/linux_raw/mm/syscalls.rs b/src/backend/linux_raw/mm/syscalls.rs
@@ -215,7 +215,7 @@ pub(crate) unsafe fn userfaultfd(flags: UserfaultfdFlags) -> io::Result<OwnedFd>
 
 /// Locks all pages mapped into the address space of the calling process.
 ///
-/// This includes the pages of the code, data and stack segment, as well as
+/// This includes the pages of the code, data, and stack segment, as well as
 /// shared libraries, user space kernel data, shared memory, and memory-mapped
 /// files. All mapped pages are guaranteed to be resident in RAM when the call
 /// returns successfully; the pages are guaranteed to stay in RAM until later
diff --git a/src/backend/linux_raw/mm/types.rs b/src/backend/linux_raw/mm/types.rs
@@ -240,9 +240,9 @@ pub enum Advice {
 impl Advice {
     /// `POSIX_MADV_DONTNEED`
     ///
-    /// On Linux, this is mapped to `POSIX_MADV_NORMAL` because
-    /// Linux's `MADV_DONTNEED` differs from `POSIX_MADV_DONTNEED`. See
-    /// `LinuxDontNeed` for the Linux behavior.
+    /// On Linux, this is mapped to `POSIX_MADV_NORMAL` because Linux's
+    /// `MADV_DONTNEED` differs from `POSIX_MADV_DONTNEED`. See `LinuxDontNeed`
+    /// for the Linux behavior.
     pub const DontNeed: Self = Self::Normal;
 }
 
@@ -271,25 +271,23 @@ bitflags! {
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MlockAllFlags: u32 {
-        /// Used together with `MCL_CURRENT`, `MCL_FUTURE`, or both.  Mark
-        /// all current (with `MCL_CURRENT`) or future (with `MCL_FUTURE`)
-        /// mappings to lock pages when they are faulted in.  When
-        /// used with `MCL_CURRENT`, all present pages are locked, but
-        /// `mlockall()` will not fault in non-present pages.  When used
-        /// with `MCL_FUTURE`, all future mappings will be marked to
-        /// lock pages when they are faulted in, but they will not be
-        /// populated by the lock when the mapping is created.
-        /// `MCL_ONFAULT` must be used with either `MCL_CURRENT` or
+        /// Used together with `MCL_CURRENT`, `MCL_FUTURE`, or both. Mark all
+        /// current (with `MCL_CURRENT`) or future (with `MCL_FUTURE`) mappings
+        /// to lock pages when they are faulted in. When used with
+        /// `MCL_CURRENT`, all present pages are locked, but `mlockall` will
+        /// not fault in non-present pages. When used with `MCL_FUTURE`, all
+        /// future mappings will be marked to lock pages when they are faulted
+        /// in, but they will not be populated by the lock when the mapping is
+        /// created. `MCL_ONFAULT` must be used with either `MCL_CURRENT` or
         /// `MCL_FUTURE` or both.
         const ONFAULT = linux_raw_sys::general::MCL_ONFAULT;
-        /// Lock all pages which will become mapped into the address
-        /// space of the process in the future.  These could be, for
-        /// instance, new pages required by a growing heap and stack
-        /// as well as new memory-mapped files or shared memory
-        /// regions.
+        /// Lock all pages which will become mapped into the address space of
+        /// the process in the future. These could be, for instance, new pages
+        /// required by a growing heap and stack as well as new memory-mapped
+        /// files or shared memory regions.
         const FUTURE = linux_raw_sys::general::MCL_FUTURE;
-        /// Lock all pages which are currently mapped into the address
-        /// space of the process.
+        /// Lock all pages which are currently mapped into the address space of
+        /// the process.
         const CURRENT = linux_raw_sys::general::MCL_CURRENT;
 
         /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
diff --git a/src/backend/linux_raw/param/auxv.rs b/src/backend/linux_raw/param/auxv.rs
@@ -337,7 +337,7 @@ unsafe fn init_from_aux_iter(aux_iter: impl Iterator<Item = Elf_auxv_t>) -> Opti
     #[cfg(feature = "runtime")]
     assert_eq!(phent, size_of::<Elf_Phdr>());
 
-    // If we're running set-uid or set-gid, enable "secure execution" mode,
+    // If we're running set-uid or set-gid, enable “secure execution” mode,
     // which doesn't do much, but users may be depending on the things that
     // it does do.
     #[cfg(feature = "runtime")]
diff --git a/src/backend/linux_raw/process/syscalls.rs b/src/backend/linux_raw/process/syscalls.rs
@@ -141,7 +141,7 @@ pub(crate) fn getpgrp() -> Pid {
 #[inline]
 pub(crate) fn sched_getaffinity(pid: Option<Pid>, cpuset: &mut RawCpuSet) -> io::Result<()> {
     unsafe {
-        // The raw linux syscall returns the size (in bytes) of the `cpumask_t`
+        // The raw Linux syscall returns the size (in bytes) of the `cpumask_t`
         // data type that is used internally by the kernel to represent the CPU
         // set bit mask.
         let size = ret_usize(syscall!(
diff --git a/src/backend/linux_raw/termios/syscalls.rs b/src/backend/linux_raw/termios/syscalls.rs
@@ -278,7 +278,7 @@ pub(crate) fn ttyname(fd: BorrowedFd<'_>, buf: &mut [MaybeUninit<u8>]) -> io::Re
     // Check that `fd` is really a tty.
     tcgetwinsize(fd)?;
 
-    // Get a fd to '/proc/self/fd'.
+    // Get a fd to "/proc/self/fd".
     let proc_self_fd = procfs::proc_self_fd()?;
 
     // Gather the ttyname by reading the "fd" file inside `proc_self_fd`.
diff --git a/src/check_types.rs b/src/check_types.rs
@@ -19,8 +19,8 @@ macro_rules! check_renamed_type {
     };
 }
 
-/// Check that the field of a struct has the same offset as the
-/// corresponding field in the `sys` bindings.
+/// Check that the field of a struct has the same offset as the corresponding
+/// field in the `sys` bindings.
 macro_rules! check_struct_field {
     ($struct:ident, $field:ident) => {
         const_assert_eq!(
diff --git a/src/event/kqueue.rs b/src/event/kqueue.rs
@@ -73,11 +73,11 @@ impl Event {
                 flags: flags.bits() as _,
                 fflags,
                 data: {
-                    // On openbsd, data is an i64 and not an isize
+                    // On OpenBSD, data is an `i64` and not an `isize`.
                     data as _
                 },
                 udata: {
-                    // On netbsd, udata is an isize and not a pointer.
+                    // On NetBSD, udata is an `isize` and not a pointer.
                     // TODO: Strict provenance, prevent int-to-ptr cast.
                     udata as _
                 },
@@ -93,15 +93,15 @@ impl Event {
 
     /// Get the user data for this event.
     pub fn udata(&self) -> isize {
-        // On netbsd, udata is an isize and not a pointer.
+        // On NetBSD, udata is an isize and not a pointer.
         // TODO: Strict provenance, prevent ptr-to-int cast.
 
         self.inner.udata as _
     }
 
     /// Get the raw data for this event.
     pub fn data(&self) -> i64 {
-        // On some bsds, data is an isize and not an i64
+        // On some BSDs, data is an `isize` and not an `i64`.
         self.inner.data as _
     }
 
diff --git a/src/fs/at.rs b/src/fs/at.rs
@@ -105,22 +105,22 @@ 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 {
                 buffer.set_len(nread);
             }
 
             // SAFETY:
-            // - "readlink places the contents of the symbolic link pathname in the buffer
-            //   buf"
-            // - [POSIX definition 3.271: Pathname]: "A string that is used to identify a
-            //   file."
-            // - [POSIX definition 3.375: String]: "A contiguous sequence of bytes
-            //   terminated by and including the first null byte."
-            // - "readlink does not append a terminating null byte to buf."
+            // - “readlink places the contents of the symbolic link pathname in
+            //   the buffer buf”
+            // - [POSIX definition 3.271: Pathname]: “A string that is used to
+            //   identify a file.”
+            // - [POSIX definition 3.375: String]: “A contiguous sequence of
+            //   bytes terminated by and including the first null byte.”
+            // - “readlink does not append a terminating null byte to buf.”
             //
             // Thus, there will be no NUL bytes in the string.
             //
@@ -131,9 +131,8 @@ fn _readlinkat(dirfd: BorrowedFd<'_>, path: &CStr, mut buffer: Vec<u8>) -> io::R
             }
         }
 
-        buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation
-                                               // strategy to grow capacity
-                                               // exponentially
+        // Use `Vec` reallocation strategy to grow capacity exponentially.
+        buffer.reserve(buffer.capacity() + 1);
     }
 }
 
diff --git a/src/ioctl/mod.rs b/src/ioctl/mod.rs
@@ -204,7 +204,7 @@ impl Opcode {
         Self { raw }
     }
 
-    /// Create a new opcode from a direction, group, number and size.
+    /// Create a new opcode from a direction, group, number, and size.
     ///
     /// This corresponds to the C macro `_IOC(direction, group, number, size)`
     #[cfg(any(linux_kernel, bsd))]
@@ -227,8 +227,8 @@ impl Opcode {
         ))
     }
 
-    /// Create a new non-mutating opcode from a group, a number and the type of
-    /// data.
+    /// Create a new non-mutating opcode from a group, a number, and the type
+    /// of data.
     ///
     /// This corresponds to the C macro `_IO(group, number)` when `T` is zero
     /// sized.
diff --git a/src/ioctl/patterns.rs b/src/ioctl/patterns.rs
@@ -49,7 +49,7 @@ unsafe impl<Opcode: CompileTimeOpcode> Ioctl for NoArg<Opcode> {
     }
 }
 
-/// Implements the traditional "getter" pattern for `ioctl`s.
+/// Implements the traditional “getter” pattern for `ioctl`s.
 ///
 /// Some `ioctl`s just read data into the userspace. As this is a popular
 /// pattern this structure implements it.
diff --git a/src/lib.rs b/src/lib.rs
@@ -115,9 +115,9 @@
 )]
 #![cfg_attr(asm_experimental_arch, feature(asm_experimental_arch))]
 #![cfg_attr(not(feature = "all-apis"), allow(dead_code))]
-// It is common in linux and libc APIs for types to vary between platforms.
+// It is common in Linux and libc APIs for types to vary between platforms.
 #![allow(clippy::unnecessary_cast)]
-// It is common in linux and libc APIs for types to vary between platforms.
+// It is common in Linux and libc APIs for types to vary between platforms.
 #![allow(clippy::useless_conversion)]
 // Redox and WASI have enough differences that it isn't worth precisely
 // conditionalizing all the `use`s for them.
diff --git a/src/mm/mmap.rs b/src/mm/mmap.rs
@@ -345,7 +345,7 @@ pub unsafe fn munlock(ptr: *mut c_void, len: usize) -> io::Result<()> {
 
 /// Locks all pages mapped into the address space of the calling process.
 ///
-/// This includes the pages of the code, data and stack segment, as well as
+/// This includes the pages of the code, data, and stack segment, as well as
 /// shared libraries, user space kernel data, shared memory, and memory-mapped
 /// files. All mapped pages are guaranteed to be resident in RAM when the call
 /// returns successfully; the pages are guaranteed to stay in RAM until later
diff --git a/src/net/send_recv/msg.rs b/src/net/send_recv/msg.rs
@@ -317,7 +317,7 @@ impl<'buf> AncillaryDrain<'buf> {
         msg: &c::cmsghdr,
     ) -> Option<RecvAncillaryMessage<'buf>> {
         unsafe {
-            // Advance the "read" pointer.
+            // Advance the `read` pointer.
             let msg_len = msg.cmsg_len as usize;
             *read += msg_len;
             *length -= msg_len;
diff --git a/src/net/sockopt.rs b/src/net/sockopt.rs
@@ -1067,8 +1067,8 @@ pub fn get_ipv6_freebind<Fd: AsFd>(fd: Fd) -> io::Result<bool> {
 
 /// `getsockopt(fd, IPPROTO_IP, SO_ORIGINAL_DST)`
 ///
-/// Even though this corresponnds to a `SO_*` constant, it is an
-/// `IPPROTO_IP` option.
+/// Even though this corresponnds to a `SO_*` constant, it is an `IPPROTO_IP`
+/// option.
 ///
 /// See the [module-level documentation] for more.
 ///
diff --git a/src/pipe.rs b/src/pipe.rs
@@ -156,9 +156,9 @@ pub fn splice<FdIn: AsFd, FdOut: AsFd>(
 /// the pipe is placed in `fd`.
 ///
 /// Additionally if `SpliceFlags::GIFT` is set, the caller must also ensure
-/// that the contents of `bufs` in never modified following the call,
-/// and that all of the pointers in `bufs` are page aligned,
-/// and the lengths are multiples of a page size in bytes.
+/// that the contents of `bufs` in never modified following the call, and that
+/// all of the pointers in `bufs` are page aligned, and the lengths are
+/// multiples of a page size in bytes.
 ///
 /// # References
 ///  - [Linux]
diff --git a/src/process/chdir.rs b/src/process/chdir.rs
@@ -67,13 +67,15 @@ fn _getcwd(mut buffer: Vec<u8>) -> io::Result<CString> {
     loop {
         match backend::process::syscalls::getcwd(buffer.spare_capacity_mut()) {
             Err(io::Errno::RANGE) => {
-                buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation strategy to grow capacity exponentially
+                // Use `Vec` reallocation strategy to grow capacity
+                // exponentially.
+                buffer.reserve(buffer.capacity() + 1);
             }
             Ok(_) => {
                 // SAFETY:
                 // - "These functions return a null-terminated string"
-                // - [POSIX definition 3.375: String]: "A contiguous sequence of bytes
-                //   terminated by and including the first null byte."
+                // - [POSIX definition 3.375: String]: "A contiguous sequence
+                //   of bytes terminated by and including the first null byte."
                 //
                 // Thus, there will be a single NUL byte at the end of the
                 // string.
diff --git a/src/process/prctl.rs b/src/process/prctl.rs
@@ -764,8 +764,8 @@ pub struct PrctlMmMap {
 ///
 /// # Safety
 ///
-/// Please ensure the conditions necessary to safely call this function,
-/// as detailed in the references above.
+/// Please ensure the conditions necessary to safely call this function, as
+/// detailed in the references above.
 ///
 /// [`prctl(PR_SET_MM,PR_SET_MM_MAP,...)`]: https://man7.org/linux/man-pages/man2/prctl.2.html
 #[inline]
diff --git a/src/runtime.rs b/src/runtime.rs
diff --git a/src/system.rs b/src/system.rs
diff --git a/src/termios/tty.rs b/src/termios/tty.rs
diff --git a/src/thread/prctl.rs b/src/thread/prctl.rs
diff --git a/tests/pty/openpty.rs b/tests/pty/openpty.rs
