Miscellaneous documentation cleanups. (#860)

Author: sunfishcode

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

@@ -742,8 +742,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.
 ///
@@ -851,8 +851,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.
 ///