From ee20967cad28993a8e639441494ea25277c3cb56 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Thu, 28 Sep 2023 22:47:05 -0700 Subject: [PATCH] Miscellaneous documentation cleanups. --- Cargo.toml | 4 ++-- README.md | 2 ++ src/backend/libc/net/send_recv.rs | 6 ++++-- src/backend/linux_raw/net/send_recv.rs | 6 ++++-- src/fs/mount.rs | 6 +++--- src/fs/statx.rs | 5 +++-- src/lib.rs | 1 + src/mm/mmap.rs | 7 ++++--- src/net/send_recv/msg.rs | 9 +++++---- src/net/sockopt.rs | 8 ++++---- src/process/prctl.rs | 15 ++++++++++----- src/shm.rs | 9 +++++---- src/thread/prctl.rs | 6 ++++-- 13 files changed, 51 insertions(+), 33 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 42ca74328..c04f57d99 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -121,7 +121,7 @@ targets = [ # users are better served by just using libc for this. default = ["std", "use-libc-auxv"] -# This enables use of std. Disabling this enables `#![no_std], and requires +# This enables use of std. Disabling this enables `#![no_std]`, and requires # Rust 1.64 or newer. std = ["bitflags/std", "alloc", "libc?/std", "libc_errno?/std"] @@ -202,8 +202,8 @@ all-apis = [ "rand", "runtime", "shm", - "system", "stdio", + "system", "termios", "thread", "time", diff --git a/README.md b/README.md index 96def6e1f..dbd79fafb 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,7 @@ by default. The rest of the API is conditional with cargo feature flags: | `procfs` | [`rustix::procfs`]—Utilities for reading `/proc` on Linux. | `pty` | [`rustix::pty`]—Pseudoterminal operations. | `rand` | [`rustix::rand`]—Random-related operations. +| `shm` | [`rustix::shm`]—POSIX shared memory. | `stdio` | [`rustix::stdio`]—Stdio-related operations. | `system` | [`rustix::system`]—System-related operations. | `termios` | [`rustix::termios`]—Terminal I/O stream operations. @@ -89,6 +90,7 @@ by default. The rest of the API is conditional with cargo feature flags: [`rustix::procfs`]: https://docs.rs/rustix/*/rustix/procfs/index.html [`rustix::pty`]: https://docs.rs/rustix/*/rustix/pty/index.html [`rustix::rand`]: https://docs.rs/rustix/*/rustix/rand/index.html +[`rustix::shm`]: https://docs.rs/rustix/*/rustix/shm/index.html [`rustix::stdio`]: https://docs.rs/rustix/*/rustix/stdio/index.html [`rustix::system`]: https://docs.rs/rustix/*/rustix/system/index.html [`rustix::termios`]: https://docs.rs/rustix/*/rustix/termios/index.html diff --git a/src/backend/libc/net/send_recv.rs b/src/backend/libc/net/send_recv.rs index 76dc97e78..4d99eb60f 100644 --- a/src/backend/libc/net/send_recv.rs +++ b/src/backend/libc/net/send_recv.rs @@ -2,7 +2,8 @@ use crate::backend::c; use bitflags::bitflags; bitflags! { - /// `MSG_* flags for use with [`send`], [`send_to`], and related functions. + /// `MSG_*` flags for use with [`send`], [`send_to`], and related + /// functions. /// /// [`send`]: crate::net::send /// [`sendto`]: crate::net::sendto @@ -50,7 +51,8 @@ bitflags! { } bitflags! { - /// `MSG_* flags for use with [`recv`], [`recvfrom`], and related functions. + /// `MSG_*` flags for use with [`recv`], [`recvfrom`], and related + /// functions. /// /// [`recv`]: crate::net::recv /// [`recvfrom`]: crate::net::recvfrom diff --git a/src/backend/linux_raw/net/send_recv.rs b/src/backend/linux_raw/net/send_recv.rs index 43b35341a..69419207d 100644 --- a/src/backend/linux_raw/net/send_recv.rs +++ b/src/backend/linux_raw/net/send_recv.rs @@ -2,7 +2,8 @@ use crate::backend::c; use bitflags::bitflags; bitflags! { - /// `MSG_* flags for use with [`send`], [`send_to`], and related functions. + /// `MSG_*` flags for use with [`send`], [`send_to`], and related + /// functions. /// /// [`send`]: crate::net::send /// [`sendto`]: crate::net::sendto @@ -30,7 +31,8 @@ bitflags! { } bitflags! { - /// `MSG_* flags for use with [`recv`], [`recvfrom`], and related functions. + /// `MSG_*` flags for use with [`recv`], [`recvfrom`], and related + /// functions. /// /// [`recv`]: crate::net::recv /// [`recvfrom`]: crate::net::recvfrom diff --git a/src/fs/mount.rs b/src/fs/mount.rs index 0f04b7f69..bd44aaa7d 100644 --- a/src/fs/mount.rs +++ b/src/fs/mount.rs @@ -2,16 +2,16 @@ //! //! These have been moved to a new `rustix::mount` module. -#[deprecated(note = "rustix::fs::UnmountFlags` moved to `rustix::mount::UnmountFlags`.")] +#[deprecated(note = "`rustix::fs::UnmountFlags` moved to `rustix::mount::UnmountFlags`.")] #[doc(hidden)] pub use crate::mount::UnmountFlags; -#[deprecated(note = "rustix::fs::MountFlags` moved to `rustix::mount::MountFlags`.")] +#[deprecated(note = "`rustix::fs::MountFlags` moved to `rustix::mount::MountFlags`.")] #[doc(hidden)] pub use crate::mount::MountFlags; #[deprecated( - note = "rustix::fs::MountPropagationFlags` moved to `rustix::mount::MountPropagationFlags`." + note = "`rustix::fs::MountPropagationFlags` moved to `rustix::mount::MountPropagationFlags`." )] #[doc(hidden)] pub use crate::mount::MountPropagationFlags; diff --git a/src/fs/statx.rs b/src/fs/statx.rs index 1791697af..28fd61b1d 100644 --- a/src/fs/statx.rs +++ b/src/fs/statx.rs @@ -28,8 +28,9 @@ use compat::statx as _statx; /// # use std::io; /// # use rustix::fs::{AtFlags, StatxFlags}; /// # use rustix::fd::BorrowedFd; -/// /// Try to determine if the provided path is a mount root. Will return `Ok(None)` if -/// /// the kernel is not new enough to support statx() or [`libc::STATX_ATTR_MOUNT_ROOT`]. +/// /// Try to determine if the provided path is a mount root. Will return +/// /// `Ok(None)` if the kernel is not new enough to support `statx` or +/// /// [`libc::STATX_ATTR_MOUNT_ROOT`]. /// fn is_mountpoint(root: BorrowedFd<'_>, path: &Path) -> io::Result> { /// use rustix::fs::{AtFlags, StatxFlags}; /// diff --git a/src/lib.rs b/src/lib.rs index e5f1bc287..9cc254b07 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -253,6 +253,7 @@ pub mod rand; target_os = "wasi" )))] #[cfg(feature = "shm")] +#[cfg_attr(doc_cfg, doc(cfg(feature = "shm")))] pub mod shm; #[cfg(not(windows))] #[cfg(feature = "stdio")] diff --git a/src/mm/mmap.rs b/src/mm/mmap.rs index 18bb4304c..f68a02b72 100644 --- a/src/mm/mmap.rs +++ b/src/mm/mmap.rs @@ -19,9 +19,10 @@ pub use backend::mm::types::{MapFlags, MprotectFlags, ProtFlags}; impl MapFlags { /// Create `MAP_HUGETLB` with provided size of huge page. /// - /// Under the hood it computes `MAP_HUGETLB | (huge_page_size_log2 << MAP_HUGE_SHIFT)`. - /// `huge_page_size_log2` denotes logarithm of huge page size to use and should be - /// between 16 and 63 (inclusively). + /// Under the hood it computes + /// `MAP_HUGETLB | (huge_page_size_log2 << MAP_HUGE_SHIFT)`. + /// `huge_page_size_log2` denotes logarithm of huge page size to use and + /// should be between 16 and 63 (inclusive). /// /// ``` /// use rustix::mm::MapFlags; diff --git a/src/net/send_recv/msg.rs b/src/net/send_recv/msg.rs index 431aefa03..0409bb0af 100644 --- a/src/net/send_recv/msg.rs +++ b/src/net/send_recv/msg.rs @@ -71,7 +71,8 @@ pub enum RecvAncillaryMessage<'a> { ScmRights(AncillaryIter<'a, OwnedFd>), } -/// Buffer for sending ancillary messages. +/// Buffer for sending ancillary messages with [`sendmsg`], [`sendmsg_v4`], +/// [`sendmsg_v6`], [`sendmsg_unix`], and [`sendmsg_any`]. pub struct SendAncillaryBuffer<'buf, 'slice, 'fd> { /// Raw byte buffer for messages. buffer: &'buf mut [u8], @@ -191,7 +192,7 @@ impl<'slice, 'fd> Extend> } } -/// Buffer for receiving ancillary messages. +/// Buffer for receiving ancillary messages with [`recvmsg`]. pub struct RecvAncillaryBuffer<'buf> { /// Raw byte buffer for messages. buffer: &'buf mut [u8], @@ -274,7 +275,7 @@ impl Drop for RecvAncillaryBuffer<'_> { } } -/// An iterator that drains messages from a `RecvAncillaryBuffer`. +/// An iterator that drains messages from a [`RecvAncillaryBuffer`]. pub struct AncillaryDrain<'buf> { /// Inner iterator over messages. messages: messages::Messages<'buf>, @@ -287,7 +288,7 @@ pub struct AncillaryDrain<'buf> { } impl<'buf> AncillaryDrain<'buf> { - /// A closure that converts a message into a `RecvAncillaryMessage`. + /// A closure that converts a message into a [`RecvAncillaryMessage`]. fn cvt_msg( read: &mut usize, length: &mut usize, diff --git a/src/net/sockopt.rs b/src/net/sockopt.rs index ea736c2af..c6c4cb0f8 100644 --- a/src/net/sockopt.rs +++ b/src/net/sockopt.rs @@ -617,8 +617,8 @@ pub fn get_ipv6_multicast_hops(fd: Fd) -> io::Result { /// `setsockopt(fd, IPPROTO_IP, IP_ADD_MEMBERSHIP, multiaddr, interface)` /// -/// This is similar to [`set_ip_add_membership`] but always sets `ifindex` value -/// to zero. +/// This is similar to [`set_ip_add_membership`] but always sets `ifindex` +/// value to zero. /// /// See the [module-level documentation] for more. /// @@ -726,8 +726,8 @@ pub fn set_ipv6_add_membership( /// `setsockopt(fd, IPPROTO_IP, IP_DROP_MEMBERSHIP, multiaddr, interface)` /// -/// This is similar to [`set_ip_drop_membership`] but always sets `ifindex` value -/// to zero. +/// This is similar to [`set_ip_drop_membership`] but always sets `ifindex` +/// value to zero. /// /// See the [module-level documentation] for more. /// diff --git a/src/process/prctl.rs b/src/process/prctl.rs index 59be7020f..63df49935 100644 --- a/src/process/prctl.rs +++ b/src/process/prctl.rs @@ -960,9 +960,11 @@ bitflags! { const ENABLE = 1_u32 << 1; /// The speculation feature is disabled, mitigation is enabled. const DISABLE = 1_u32 << 2; - /// The speculation feature is disabled, mitigation is enabled, and it cannot be undone. + /// The speculation feature is disabled, mitigation is enabled, and it + /// cannot be undone. const FORCE_DISABLE = 1_u32 << 3; - /// The speculation feature is disabled, mitigation is enabled, and the state will be cleared on `execve`. + /// The speculation feature is disabled, mitigation is enabled, and the + /// state will be cleared on `execve`. const DISABLE_NOEXEC = 1_u32 << 4; } } @@ -972,15 +974,18 @@ bitflags! { #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct SpeculationFeatureState: u32 { - /// Mitigation can be controlled per thread by `PR_SET_SPECULATION_CTRL`. + /// Mitigation can be controlled per thread by + /// `PR_SET_SPECULATION_CTRL`. const PRCTL = 1_u32 << 0; /// The speculation feature is enabled, mitigation is disabled. const ENABLE = 1_u32 << 1; /// The speculation feature is disabled, mitigation is enabled. const DISABLE = 1_u32 << 2; - /// The speculation feature is disabled, mitigation is enabled, and it cannot be undone. + /// The speculation feature is disabled, mitigation is enabled, and it + /// cannot be undone. const FORCE_DISABLE = 1_u32 << 3; - /// The speculation feature is disabled, mitigation is enabled, and the state will be cleared on `execve`. + /// The speculation feature is disabled, mitigation is enabled, and the + /// state will be cleared on `execve`. const DISABLE_NOEXEC = 1_u32 << 4; } } diff --git a/src/shm.rs b/src/shm.rs index 9b1f82b12..6f8fadf9f 100644 --- a/src/shm.rs +++ b/src/shm.rs @@ -8,11 +8,12 @@ pub use crate::backend::shm::types::ShmOFlags; /// `shm_open(name, oflags, mode)`—Opens a shared memory object. /// -/// For portability, `name` should begin with a slash, contain no other slashes, -/// and be no longer than an implementation-defined limit (255 on Linux). +/// For portability, `name` should begin with a slash, contain no other +/// slashes, and be no longer than an implementation-defined limit (255 on +/// Linux). /// -/// Exactly one of [ShmOFlags::RDONLY] and [ShmOFlags::RDWR] should be passed. The file -/// descriptor will be opened with `FD_CLOEXEC` set. +/// Exactly one of [`ShmOFlags::RDONLY`] and [`ShmOFlags::RDWR`] should be +/// passed. The file descriptor will be opened with `FD_CLOEXEC` set. /// /// # References /// - [POSIX] diff --git a/src/thread/prctl.rs b/src/thread/prctl.rs index b2d40d65c..50c56b405 100644 --- a/src/thread/prctl.rs +++ b/src/thread/prctl.rs @@ -742,11 +742,13 @@ const PR_MTE_TAG_SHIFT: u32 = 3; const PR_MTE_TAG_MASK: u32 = 0xffff_u32 << PR_MTE_TAG_SHIFT; bitflags! { - /// Zero means addresses that are passed for the purpose of being dereferenced by the kernel must be untagged. + /// Zero means addresses that are passed for the purpose of being + /// dereferenced by the kernel must be untagged. #[repr(transparent)] #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)] pub struct TaggedAddressMode: u32 { - /// Addresses that are passed for the purpose of being dereferenced by the kernel may be tagged. + /// Addresses that are passed for the purpose of being dereferenced by + /// the kernel may be tagged. const ENABLED = 1_u32 << 0; /// Synchronous tag check fault mode. const TCF_SYNC = 1_u32 << 1;