Miscellaneous documentation cleanups.

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

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

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

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

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;

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<Option<bool>> {
 ///     use rustix::fs::{AtFlags, StatxFlags};
 ///

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

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;

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<SendAncillaryMessage<'slice, 'fd>>
     }
 }
 
-/// 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,

src/net/sockopt.rs

@@ -617,8 +617,8 @@ pub fn get_ipv6_multicast_hops<Fd: AsFd>(fd: Fd) -> io::Result<u32> {
 
 /// `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<Fd: AsFd>(
 
 /// `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.
 ///

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

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]

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;