Miscellaneous documentation cleanups. (#955)

sunfishcode · web-flow · commit 33acaa9b01fd · 2023-11-30T14:04:26.000-08:00
diff --git a/examples/stdio.rs b/examples/stdio.rs
@@ -1,5 +1,5 @@
-//! A command which prints out information about the standard input,
-//! output, and error streams provided to it.
+//! A command which prints out information about the standard input, output,
+//! and error streams provided to it.
 
 #[cfg(feature = "termios")]
 #[cfg(all(not(windows), feature = "stdio"))]
diff --git a/src/backend/libc/event/epoll.rs b/src/backend/libc/event/epoll.rs
@@ -278,8 +278,8 @@ pub fn wait(epoll: impl AsFd, event_list: &mut EventVec, timeout: c::c_int) -> i
 /// An iterator over the `Event`s in an `EventVec`.
 pub struct Iter<'a> {
     /// Use `Copied` to copy the struct, since `Event` is `packed` on some
-    /// platforms, and it's common for users to directly destructure it,
-    /// which would lead to errors about forming references to packed fields.
+    /// platforms, and it's common for users to directly destructure it, which
+    /// would lead to errors about forming references to packed fields.
     iter: core::iter::Copied<slice::Iter<'a, Event>>,
 }
 
diff --git a/src/backend/libc/event/poll_fd.rs b/src/backend/libc/event/poll_fd.rs
@@ -12,7 +12,7 @@ use {
 bitflags! {
     /// `POLL*` flags for use with [`poll`].
     ///
-    /// [`poll`]: crate::io::poll
+    /// [`poll`]: crate::event::poll
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct PollFlags: c::c_short {
diff --git a/src/backend/libc/event/types.rs b/src/backend/libc/event/types.rs
@@ -17,7 +17,7 @@ use bitflags::bitflags;
 bitflags! {
     /// `EFD_*` flags for use with [`eventfd`].
     ///
-    /// [`eventfd`]: crate::io::eventfd
+    /// [`eventfd`]: crate::event::eventfd
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct EventfdFlags: u32 {
diff --git a/src/backend/libc/fs/syscalls.rs b/src/backend/libc/fs/syscalls.rs
@@ -1699,7 +1699,7 @@ pub(crate) fn ftruncate(fd: BorrowedFd<'_>, length: u64) -> io::Result<()> {
 }
 
 #[cfg(any(linux_kernel, target_os = "freebsd"))]
-pub(crate) fn memfd_create(path: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd> {
+pub(crate) fn memfd_create(name: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd> {
     #[cfg(target_os = "freebsd")]
     weakcall! {
         fn memfd_create(
@@ -1716,7 +1716,7 @@ pub(crate) fn memfd_create(path: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd
         ) via SYS_memfd_create -> c::c_int
     }
 
-    unsafe { ret_owned_fd(memfd_create(c_str(path), bitflags_bits!(flags))) }
+    unsafe { ret_owned_fd(memfd_create(c_str(name), bitflags_bits!(flags))) }
 }
 
 #[cfg(linux_kernel)]
diff --git a/src/backend/libc/mm/types.rs b/src/backend/libc/mm/types.rs
@@ -6,7 +6,7 @@ bitflags! {
     ///
     /// For `PROT_NONE`, use `ProtFlags::empty()`.
     ///
-    /// [`mmap`]: crate::io::mmap
+    /// [`mmap`]: crate::mm::mmap
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ProtFlags: u32 {
@@ -27,7 +27,7 @@ bitflags! {
     ///
     /// For `PROT_NONE`, use `MprotectFlags::empty()`.
     ///
-    /// [`mprotect`]: crate::io::mprotect
+    /// [`mprotect`]: crate::mm::mprotect
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MprotectFlags: u32 {
@@ -69,8 +69,8 @@ bitflags! {
     ///
     /// For `MAP_ANONYMOUS` (aka `MAP_ANON`), see [`mmap_anonymous`].
     ///
-    /// [`mmap`]: crate::io::mmap
-    /// [`mmap_anonymous`]: crates::io::mmap_anonymous
+    /// [`mmap`]: crate::mm::mmap
+    /// [`mmap_anonymous`]: crates::mm::mmap_anonymous
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MapFlags: u32 {
@@ -242,8 +242,8 @@ bitflags! {
     ///
     /// For `MREMAP_FIXED`, see [`mremap_fixed`].
     ///
-    /// [`mremap`]: crate::io::mremap
-    /// [`mremap_fixed`]: crate::io::mremap_fixed
+    /// [`mremap`]: crate::mm::mremap
+    /// [`mremap_fixed`]: crate::mm::mremap_fixed
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MremapFlags: u32 {
@@ -258,7 +258,7 @@ bitflags! {
 bitflags! {
     /// `MS_*` flags for use with [`msync`].
     ///
-    /// [`msync`]: crate::io::msync
+    /// [`msync`]: crate::mm::msync
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MsyncFlags: u32 {
@@ -281,7 +281,7 @@ bitflags! {
 bitflags! {
     /// `MLOCK_*` flags for use with [`mlock_with`].
     ///
-    /// [`mlock_with`]: crate::io::mlock_with
+    /// [`mlock_with`]: crate::mm::mlock_with
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MlockFlags: u32 {
@@ -429,7 +429,7 @@ impl Advice {
 bitflags! {
     /// `O_*` flags for use with [`userfaultfd`].
     ///
-    /// [`userfaultfd`]: crate::io::userfaultfd
+    /// [`userfaultfd`]: crate::mm::userfaultfd
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct UserfaultfdFlags: u32 {
diff --git a/src/backend/libc/pipe/types.rs b/src/backend/libc/pipe/types.rs
@@ -7,7 +7,7 @@ use {crate::backend::c, bitflags::bitflags};
 bitflags! {
     /// `O_*` constants for use with [`pipe_with`].
     ///
-    /// [`pipe_with`]: crate::io::pipe_with
+    /// [`pipe_with`]: crate::pipe::pipe_with
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct PipeFlags: u32 {
@@ -34,8 +34,8 @@ bitflags! {
 
 #[cfg(linux_kernel)]
 bitflags! {
-    /// `SPLICE_F_*` constants for use with [`splice`], [`vmsplice`],
-    /// and [`tee`].
+    /// `SPLICE_F_*` constants for use with [`splice`], [`vmsplice`], and
+    /// [`tee`].
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct SpliceFlags: c::c_uint {
diff --git a/src/backend/linux_raw/event/epoll.rs b/src/backend/linux_raw/event/epoll.rs
@@ -262,8 +262,8 @@ pub fn wait(epoll: impl AsFd, event_list: &mut EventVec, timeout: c::c_int) -> i
 /// An iterator over the `Event`s in an `EventVec`.
 pub struct Iter<'a> {
     /// Use `Copied` to copy the struct, since `Event` is `packed` on some
-    /// platforms, and it's common for users to directly destructure it,
-    /// which would lead to errors about forming references to packed fields.
+    /// platforms, and it's common for users to directly destructure it, which
+    /// would lead to errors about forming references to packed fields.
     iter: core::iter::Copied<slice::Iter<'a, Event>>,
 }
 
diff --git a/src/backend/linux_raw/event/types.rs b/src/backend/linux_raw/event/types.rs
@@ -4,7 +4,7 @@ use bitflags::bitflags;
 bitflags! {
     /// `EFD_*` flags for use with [`eventfd`].
     ///
-    /// [`eventfd`]: crate::io::eventfd
+    /// [`eventfd`]: crate::event::eventfd
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct EventfdFlags: c::c_uint {
diff --git a/src/backend/linux_raw/mm/syscalls.rs b/src/backend/linux_raw/mm/syscalls.rs
@@ -6,9 +6,8 @@
 #![allow(unsafe_code)]
 #![allow(clippy::undocumented_unsafe_blocks)]
 
-use super::types::MlockAllFlags;
 use super::types::{
-    Advice, MapFlags, MlockFlags, MprotectFlags, MremapFlags, MsyncFlags, ProtFlags,
+    Advice, MapFlags, MlockAllFlags, MlockFlags, MprotectFlags, MremapFlags, MsyncFlags, ProtFlags,
     UserfaultfdFlags,
 };
 use crate::backend::c;
diff --git a/src/backend/linux_raw/mm/types.rs b/src/backend/linux_raw/mm/types.rs
@@ -6,7 +6,7 @@ bitflags! {
     ///
     /// For `PROT_NONE`, use `ProtFlags::empty()`.
     ///
-    /// [`mmap`]: crate::io::mmap
+    /// [`mmap`]: crate::mm::mmap
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct ProtFlags: u32 {
@@ -27,7 +27,7 @@ bitflags! {
     ///
     /// For `PROT_NONE`, use `MprotectFlags::empty()`.
     ///
-    /// [`mprotect`]: crate::io::mprotect
+    /// [`mprotect`]: crate::mm::mprotect
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MprotectFlags: u32 {
@@ -66,8 +66,8 @@ bitflags! {
     ///
     /// For `MAP_ANONYMOUS` (aka `MAP_ANON`), see [`mmap_anonymous`].
     ///
-    /// [`mmap`]: crate::io::mmap
-    /// [`mmap_anonymous`]: crates::io::mmap_anonymous
+    /// [`mmap`]: crate::mm::mmap
+    /// [`mmap_anonymous`]: crates::mm::mmap_anonymous
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MapFlags: u32 {
@@ -116,8 +116,8 @@ bitflags! {
     ///
     /// For `MREMAP_FIXED`, see [`mremap_fixed`].
     ///
-    /// [`mremap`]: crate::io::mremap
-    /// [`mremap_fixed`]: crate::io::mremap_fixed
+    /// [`mremap`]: crate::mm::mremap
+    /// [`mremap_fixed`]: crate::mm::mremap_fixed
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MremapFlags: u32 {
@@ -134,7 +134,7 @@ bitflags! {
 bitflags! {
     /// `MS_*` flags for use with [`msync`].
     ///
-    /// [`msync`]: crate::io::msync
+    /// [`msync`]: crate::mm::msync
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MsyncFlags: u32 {
@@ -156,7 +156,7 @@ bitflags! {
 bitflags! {
     /// `MLOCK_*` flags for use with [`mlock_with`].
     ///
-    /// [`mlock_with`]: crate::io::mlock_with
+    /// [`mlock_with`]: crate::mm::mlock_with
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MlockFlags: u32 {
@@ -249,7 +249,7 @@ impl Advice {
 bitflags! {
     /// `O_*` flags for use with [`userfaultfd`].
     ///
-    /// [`userfaultfd`]: crate::io::userfaultfd
+    /// [`userfaultfd`]: crate::mm::userfaultfd
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct UserfaultfdFlags: c::c_uint {
diff --git a/src/backend/linux_raw/pipe/types.rs b/src/backend/linux_raw/pipe/types.rs
@@ -5,7 +5,7 @@ use core::marker::PhantomData;
 bitflags! {
     /// `O_*` constants for use with [`pipe_with`].
     ///
-    /// [`pipe_with`]: crate::io::pipe_with
+    /// [`pipe_with`]: crate::pipe::pipe_with
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct PipeFlags: c::c_uint {
diff --git a/src/backend/linux_raw/vdso_wrappers.rs b/src/backend/linux_raw/vdso_wrappers.rs
@@ -42,7 +42,7 @@ use linux_raw_sys::general::timespec as __kernel_old_timespec;
     feature = "time"
 ))]
 use {super::c, super::conv::ret, core::mem::MaybeUninit};
-#[cfg(any(feature = "time"))]
+#[cfg(feature = "time")]
 use {
     super::conv::c_int,
     crate::clockid::{ClockId, DynamicClockId},
diff --git a/src/clockid.rs b/src/clockid.rs
@@ -78,6 +78,8 @@ pub enum ClockId {
     ///
     /// On FreeBSD, use [`Self::Uptime`], as `CLOCK_BOOTTIME` is an alias for
     /// `CLOCK_UPTIME`.
+    ///
+    /// [`Self::Uptime`]: https://docs.rs/rustix/*/x86_64-unknown-freebsd/rustix/time/enum.ClockId.html#variant.Uptime
     #[cfg(any(linux_kernel, target_os = "fuchsia", target_os = "openbsd"))]
     #[doc(alias = "CLOCK_BOOTTIME")]
     Boottime = bitcast!(c::CLOCK_BOOTTIME),
diff --git a/src/fs/abs.rs b/src/fs/abs.rs
@@ -269,10 +269,10 @@ pub fn statfs<P: path::Arg>(path: P) -> io::Result<StatFs> {
 
 /// `statvfs`—Queries filesystem metadata, POSIX version.
 ///
-/// Compared to [`statfs`], this function often provides less information,
-/// but it is more portable. But even so, filesystems are very diverse and not
-/// all the fields are meaningful for every filesystem. And `f_fsid` doesn't
-/// seem to have a clear meaning anywhere.
+/// Compared to [`statfs`], this function often provides less information, but
+/// it is more portable. But even so, filesystems are very diverse and not all
+/// the fields are meaningful for every filesystem. And `f_fsid` doesn't seem
+/// to have a clear meaning anywhere.
 ///
 /// # References
 ///  - [POSIX]
diff --git a/src/fs/memfd_create.rs b/src/fs/memfd_create.rs
@@ -2,7 +2,7 @@ use crate::fd::OwnedFd;
 use crate::{backend, io, path};
 use backend::fs::types::MemfdFlags;
 
-/// `memfd_create(path, flags)`
+/// `memfd_create(name, flags)`
 ///
 /// # References
 ///  - [Linux]
@@ -13,6 +13,6 @@ use backend::fs::types::MemfdFlags;
 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Memory_002dmapped-I_002fO.html#index-memfd_005fcreate
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?memfd_create
 #[inline]
-pub fn memfd_create<P: path::Arg>(path: P, flags: MemfdFlags) -> io::Result<OwnedFd> {
-    path.into_with_c_str(|path| backend::fs::syscalls::memfd_create(path, flags))
+pub fn memfd_create<P: path::Arg>(name: P, flags: MemfdFlags) -> io::Result<OwnedFd> {
+    name.into_with_c_str(|name| backend::fs::syscalls::memfd_create(name, flags))
 }
diff --git a/src/io/fcntl.rs b/src/io/fcntl.rs
@@ -105,8 +105,8 @@ pub fn fcntl_dupfd_cloexec<Fd: AsFd>(fd: Fd, min: RawFd) -> io::Result<OwnedFd>
     backend::io::syscalls::fcntl_dupfd_cloexec(fd.as_fd(), min)
 }
 
-/// `fcntl(fd, F_DUPFD)`—Creates a new `OwnedFd` instance, with value at least
-/// `min`, that shares the same underlying [file description] as `fd`.
+/// `fcntl(fd, F_DUPFD)`—Creates a new `OwnedFd` instance, with value at
+/// least `min`, that shares the same underlying [file description] as `fd`.
 ///
 /// POSIX guarantees that `F_DUPFD` will use the lowest unused file descriptor
 /// which is at least `min`, however it is not safe in general to rely on this,
diff --git a/src/ioctl/mod.rs b/src/ioctl/mod.rs
@@ -65,15 +65,14 @@ use bsd as platform;
 /// `ioctl` call is safe to make.
 ///
 /// # References
-///
-/// - [Linux]
-/// - [WinSock2]
-/// - [FreeBSD]
-/// - [NetBSD]
-/// - [OpenBSD]
-/// - [Apple]
-/// - [Solaris]
-/// - [illumos]
+///  - [Linux]
+///  - [WinSock2]
+///  - [FreeBSD]
+///  - [NetBSD]
+///  - [OpenBSD]
+///  - [Apple]
+///  - [Solaris]
+///  - [illumos]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/ioctl.2.html
 /// [Winsock2]: https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-ioctlsocket
diff --git a/src/ioctl/patterns.rs b/src/ioctl/patterns.rs
@@ -184,6 +184,7 @@ impl<'a, Opcode: CompileTimeOpcode, Value> Updater<'a, Opcode, Value> {
 
 unsafe impl<'a, Opcode: CompileTimeOpcode, T> Ioctl for Updater<'a, Opcode, T> {
     type Output = ();
+
     const IS_MUTATING: bool = true;
     const OPCODE: self::Opcode = Opcode::OPCODE;
 
diff --git a/src/mm/mmap.rs b/src/mm/mmap.rs
@@ -157,8 +157,8 @@ pub unsafe fn munmap(ptr: *mut c_void, len: usize) -> io::Result<()> {
     backend::mm::syscalls::munmap(ptr, len)
 }
 
-/// `mremap(old_address, old_size, new_size, flags)`—Resize, modify,
-/// and/or move a memory mapping.
+/// `mremap(old_address, old_size, new_size, flags)`—Resize, modify, and/or
+/// move a memory mapping.
 ///
 /// For moving a mapping to a fixed address (`MREMAP_FIXED`), see
 /// [`mremap_fixed`].
diff --git a/src/pipe.rs b/src/pipe.rs
@@ -116,10 +116,10 @@ pub fn pipe_with(flags: PipeFlags) -> io::Result<(OwnedFd, OwnedFd)> {
 /// `fd_in` to the file descriptor `fd_out`, where one of the file descriptors
 /// must refer to a pipe.
 ///
-/// `off_*` must be `None` if the corresponding fd refers to a pipe.
-/// Otherwise its value points to the starting offset to the file, from which
-/// the data is read/written. On success, the number of bytes read/written is
-/// added to the offset.
+/// `off_*` must be `None` if the corresponding fd refers to a pipe. Otherwise
+/// its value points to the starting offset to the file, from which the data is
+/// read/written. On success, the number of bytes read/written is added to the
+/// offset.
 ///
 /// Passing `None` causes the read/write to start from the file offset, and the
 /// file offset is adjusted appropriately.
@@ -143,11 +143,11 @@ pub fn splice<FdIn: AsFd, FdOut: AsFd>(
 
 /// `vmsplice(fd, bufs, flags)`—Transfer data between memory and a pipe.
 ///
-/// If `fd` is the write end of the pipe,
-/// the function maps the memory pointer at by `bufs` to the pipe.
+/// If `fd` is the write end of the pipe, the function maps the memory pointer
+/// at by `bufs` to the pipe.
 ///
-/// If `fd` is the read end of the pipe,
-/// the function writes data from the pipe to said memory.
+/// If `fd` is the read end of the pipe, the function writes data from the pipe
+/// to said memory.
 ///
 /// # Safety
 ///
diff --git a/src/process/wait.rs b/src/process/wait.rs
@@ -37,7 +37,7 @@ bitflags! {
         /// Return immediately if no child has exited.
         const NOHANG = bitcast!(backend::process::wait::WNOHANG);
         /// Return if a stopped child has been resumed by delivery of
-        /// [`Signal::Cont`]
+        /// [`Signal::Cont`].
         const CONTINUED = bitcast!(backend::process::wait::WCONTINUED);
         /// Wait for processed that have exited.
         const EXITED = bitcast!(backend::process::wait::WEXITED);
diff --git a/src/runtime.rs b/src/runtime.rs
diff --git a/src/thread/prctl.rs b/src/thread/prctl.rs

Original file line number	Diff line number	Diff line change
`@@ -1699,7 +1699,7 @@ pub(crate) fn ftruncate(fd: BorrowedFd<'_>, length: u64) -> io::Result<()> {`
`1699`	`1699`	`}`
`1700`	`1700`
`1701`	`1701`	`#[cfg(any(linux_kernel, target_os = "freebsd"))]`
`1702`		`-pub(crate) fn memfd_create(path: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd> {`
	`1702`	`+pub(crate) fn memfd_create(name: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd> {`
`1703`	`1703`	`#[cfg(target_os = "freebsd")]`
`1704`	`1704`	`weakcall! {`
`1705`	`1705`	`fn memfd_create(`
`@@ -1716,7 +1716,7 @@ pub(crate) fn memfd_create(path: &CStr, flags: MemfdFlags) -> io::Result<OwnedFd`
`1716`	`1716`	`) via SYS_memfd_create -> c::c_int`
`1717`	`1717`	`}`
`1718`	`1718`
`1719`		`- unsafe { ret_owned_fd(memfd_create(c_str(path), bitflags_bits!(flags))) }`
	`1719`	`+ unsafe { ret_owned_fd(memfd_create(c_str(name), bitflags_bits!(flags))) }`
`1720`	`1720`	`}`
`1721`	`1721`
`1722`	`1722`	`#[cfg(linux_kernel)]`