Miscellaneous documentation cleanups. (#955)

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"))]

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>>,
 }
 

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 {

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 {

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)]

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 {

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 {

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>>,
 }
 

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 {

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;

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 {

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 {

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},

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),

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]

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))
 }

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,

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

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;
 

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`].

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
 ///

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);