Improve comments and documentation. (#1332)

Author: sunfishcode

Cargo.toml

@@ -110,7 +110,7 @@ targets = [
 default = ["std", "use-libc-auxv"]
 
 # This enables use of std. Disabling this enables `#![no_std]`, and requires
-# Rust 1.64 or newer.
+# Rust 1.77 or newer.
 std = ["bitflags/std", "alloc", "libc?/std", "libc_errno?/std"]
 
 # Enable this to request the libc backend.
@@ -172,6 +172,9 @@ system = ["linux-raw-sys/system"]
 runtime = ["linux-raw-sys/prctl"]
 
 # Enable all API features.
+#
+# This is primarily intended for rustix developers. Users are encouraged to
+# enable only those features they need.
 all-apis = [
     "event",
     "fs",

src/backend/libc/fs/dir.rs

@@ -330,9 +330,9 @@ impl DirEntry {
         &self.name
     }
 
-    /// Returns the "offset" of this directory entry. Note that this is not
-    /// a true numerical offset but an opaque cookie that identifies a
-    /// position in the given stream.
+    /// Returns the “offset” of this directory entry. This is not a true
+    /// numerical offset but an opaque cookie that identifies a position in the
+    /// given stream.
     #[cfg(any(
         linux_like,
         solarish,

src/backend/libc/fs/syscalls.rs

@@ -2267,7 +2267,7 @@ fn times_to_attrlist(times: &Timestamps) -> io::Result<(c::size_t, [c::timespec;
 #[cfg(apple)]
 type Attrgroup = u32;
 
-/// Attribute list for use with `setattrlist`.
+/// Attribute list for use with [`setattrlist`].
 #[cfg(apple)]
 #[repr(C)]
 struct Attrlist {

src/backend/libc/fs/types.rs

@@ -332,16 +332,17 @@ bitflags! {
 
         /// `O_LARGEFILE`
         ///
-        /// Note that rustix and/or libc will automatically set this flag when appropriate on
-        /// `open(2)` and friends, thus typical users do not need to care about it.
-        /// It will may be reported in return of `fcntl_getfl`, though.
+        /// Rustix and/or libc will automatically set this flag when
+        /// appropriate in the [`rustix::fs::open`] family of functions, so
+        /// typical users do not need to care about it. It may be reported in
+        /// the return of `fcntl_getfl`, though.
         #[cfg(any(linux_kernel, solarish))]
         const LARGEFILE = bitcast!(c::O_LARGEFILE);
 
         /// `O_ASYNC`, `FASYNC`
         ///
-        /// Note that this flag can't be used with [`rustix::fs::open`] family of functions, use
-        /// [`rustix::fs::fcntl_setfl`] instead
+        /// This flag can't be used with the [`rustix::fs::open`] family of
+        /// functions, use [`rustix::fs::fcntl_setfl`] instead.
         #[cfg(not(any(
             target_os = "aix",
             target_os = "espidf",
@@ -994,7 +995,7 @@ pub type StatFs = c::statfs;
 #[cfg(linux_like)]
 pub type StatFs = c::statfs64;
 
-/// `fsid_t` for use with `StatFs`.
+/// `fsid_t` for use with [`StatFs`].
 #[cfg(not(any(
     solarish,
     target_os = "espidf",

src/backend/libc/mount/types.rs

@@ -147,7 +147,7 @@ pub(crate) enum FsConfigCmd {
     /// `FSCONFIG_CMD_RECONFIGURE`
     Reconfigure = 7,
 
-    /// `FSCONFIG_CMD_CREATE_EXCL`
+    /// `FSCONFIG_CMD_CREATE_EXCL` (since Linux 6.6)
     CreateExclusive = 8,
 }
 

src/backend/libc/net/addr.rs

@@ -79,9 +79,8 @@ impl SocketAddrUnix {
     /// Construct a new unnamed address.
     ///
     /// The kernel will assign an abstract Unix-domain address to the socket
-    /// when you call [`bind_unix()`][crate::net::bind_unix]. You can
-    /// inspect the assigned name with
-    /// [`getsockname`][crate::net::getsockname].
+    /// when you call [`bind`][crate::net::bind]. You can inspect the assigned
+    /// name with [`getsockname`][crate::net::getsockname].
     ///
     /// # References
     ///  - [Linux]
@@ -238,6 +237,9 @@ impl fmt::Debug for SocketAddrUnix {
 }
 
 /// `struct sockaddr_storage`.
+///
+/// This type is guaranteed to be large enough to hold any encoded socket
+/// address.
 #[repr(transparent)]
 #[derive(Copy, Clone)]
 pub struct SocketAddrStorage(c::sockaddr_storage);

src/backend/libc/net/read_sockaddr.rs

@@ -101,7 +101,7 @@ pub(crate) unsafe fn read_sa_family(storage: *const c::sockaddr) -> u16 {
 #[cfg(apple)]
 #[inline]
 unsafe fn read_sun_path0(storage: *const c::sockaddr) -> u8 {
-    // In `read_ss_family` we assert that we know the layout of `sockaddr`.
+    // In `read_sa_family` we assert that we know the layout of `sockaddr`.
     storage
         .cast::<u8>()
         .add(super::addr::offsetof_sun_path())

src/backend/libc/net/sockopt.rs

@@ -1086,8 +1086,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_MMAP_OFFSETS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<c::xdp_mmap_offsets_v1>() {
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -1121,8 +1121,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
             size_of::<xdp_mmap_offsets>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -1165,8 +1165,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_STATISTICS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<xdp_statistics_v1>() {
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,
@@ -1182,8 +1182,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
             size_of::<xdp_statistics>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,

src/backend/libc/system/syscalls.rs

@@ -83,7 +83,7 @@ pub(crate) fn setdomainname(name: &[u8]) -> io::Result<()> {
     }
 }
 
-// https://github.com/rust-lang/libc/pull/4212
+// <https://github.com/rust-lang/libc/pull/4212>
 #[cfg(target_os = "android")]
 pub(crate) fn setdomainname(name: &[u8]) -> io::Result<()> {
     syscall! {

src/backend/libc/termios/types.rs

@@ -1,3 +1,5 @@
+//! Types for the `termios` module.
+
 #![allow(non_camel_case_types)]
 
 #[cfg(not(target_os = "redox"))]

src/backend/linux_raw/arch/mips64r6.rs

@@ -7,8 +7,8 @@
 //! MIPS-family platforms have a special calling convention for `__NR_pipe`,
 //! however we use `__NR_pipe2` instead to avoid having to implement it.
 //!
-//! Note that MIPS R6 inline assembly currently doesn't differ from MIPS,
-//! because no explicit call of R6-only or R2-only instructions exist here.
+//! MIPS R6 inline assembly currently doesn't differ from MIPS, because no
+//! explicit call of R6-only or R2-only instructions exist here.
 
 use crate::backend::reg::{
     ArgReg, FromAsm, RetReg, SyscallNumber, ToAsm, A0, A1, A2, A3, A4, A5, R0,

src/backend/linux_raw/fs/dir.rs

@@ -87,7 +87,7 @@ impl Dir {
     ///
     /// [`libc::seekdir`]: https://docs.rs/libc/latest/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html
     // In the linux_raw backend here, we don't use `libc::seekdir` and don't
-    // have this limitattion, but it's a goal of rustix to support the same API
+    // have this limitation, but it's a goal of rustix to support the same API
     // on both the linux_raw and libc backends.
     #[cfg(target_pointer_width = "64")]
     #[cfg_attr(docsrs, doc(cfg(target_pointer_width = "64")))]
@@ -315,9 +315,9 @@ impl DirEntry {
         &self.name
     }
 
-    /// Returns the "offset" of this directory entry. Note that this is not
-    /// a true numerical offset but an opaque cookie that identifies a
-    /// position in the given stream.
+    /// Returns the “offset” of this directory entry. This is not a true
+    /// numerical offset but an opaque cookie that identifies a position in the
+    /// given stream.
     #[inline]
     pub fn offset(&self) -> i64 {
         self.d_off

src/backend/linux_raw/fs/types.rs

@@ -252,15 +252,16 @@ bitflags! {
 
         /// `O_LARGEFILE`
         ///
-        /// Note that rustix and/or libc will automatically set this flag when appropriate on
-        /// `open(2)` and friends, thus typical users do not need to care about it.
-        /// It will may be reported in return of `fcntl_getfl`, though.
+        /// Tustix and/or libc will automatically set this flag when
+        /// appropriate in the [`rustix::fs::open`] family of functions, so
+        /// typical users do not need to care about it. It may be reported in
+        /// the return of `fcntl_getfl`, though.
         const LARGEFILE = linux_raw_sys::general::O_LARGEFILE;
 
         /// `O_ASYNC`, `FASYNC`
         ///
-        /// Note that this flag can't be used with [`rustix::fs::open`] family of functions, use
-        /// [`rustix::fs::fcntl_setfl`] instead
+        /// This flag can't be used with the [`rustix::fs::open`] family of
+        /// functions, use [`rustix::fs::fcntl_setfl`] instead.
         const ASYNC = linux_raw_sys::general::FASYNC;
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>

src/backend/linux_raw/mount/types.rs

@@ -144,7 +144,7 @@ pub(crate) enum FsConfigCmd {
     /// `FSCONFIG_CMD_RECONFIGURE`
     Reconfigure = linux_raw_sys::general::fsconfig_command::FSCONFIG_CMD_RECONFIGURE as u32,
 
-    /// `FSCONFIG_CMD_CREATE_EXCL`
+    /// `FSCONFIG_CMD_CREATE_EXCL` (since Linux 6.6)
     CreateExclusive = linux_raw_sys::general::fsconfig_command::FSCONFIG_CMD_CREATE_EXCL as u32,
 }
 

src/backend/linux_raw/net/addr.rs

@@ -67,9 +67,8 @@ impl SocketAddrUnix {
     /// Construct a new unnamed address.
     ///
     /// The kernel will assign an abstract Unix-domain address to the socket
-    /// when you call [`bind_unix()`][crate::net::bind_unix]. You can
-    /// inspect the assigned name with
-    /// [`getsockname`][crate::net::getsockname].
+    /// when you call [`bind`][crate::net::bind]. You can inspect the assigned
+    /// name with [`getsockname`][crate::net::getsockname].
     ///
     /// # References
     ///  - [Linux]
@@ -189,6 +188,9 @@ impl fmt::Debug for SocketAddrUnix {
 }
 
 /// `struct sockaddr_storage`.
+///
+/// This type is guaranteed to be large enough to hold any encoded socket
+/// address.
 #[repr(transparent)]
 #[derive(Copy, Clone)]
 pub struct SocketAddrStorage(c::sockaddr_storage);

src/backend/linux_raw/net/sockopt.rs

@@ -892,8 +892,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_MMAP_OFFSETS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<c::xdp_mmap_offsets_v1>() {
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -927,8 +927,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
             size_of::<xdp_mmap_offsets>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -971,8 +971,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_STATISTICS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<xdp_statistics_v1>() {
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,
@@ -988,8 +988,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
             size_of::<xdp_statistics>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,

src/backend/linux_raw/param/auxv.rs

@@ -399,7 +399,7 @@ unsafe fn init_from_aux_iter(aux_iter: impl Iterator<Item = Elf_auxv_t>) -> Opti
             AT_SYSINFO_EHDR => sysinfo_ehdr = check_elf_base(a_val as *mut _)?.as_ptr(),
 
             AT_BASE => {
-                // The `AT_BASE` value can be NULL in a static executable that
+                // The `AT_BASE` value can be null in a static executable that
                 // doesn't use a dynamic linker. If so, ignore it.
                 if !a_val.is_null() {
                     let _ = check_elf_base(a_val.cast())?;

src/backend/linux_raw/termios/types.rs

@@ -1,9 +1,11 @@
+//! Types for the `termios` module.
+
 #![allow(non_camel_case_types)]
 
 use crate::ffi;
 
-// We don't want to use tcflag_t directly so we don't expose linux_raw_sys
-// publicly. It appears to be c_ulong on SPARC and c_uint everywhere else.
+// We don't want to use `tcflag_t` directly so we don't expose linux_raw_sys
+// publicly. It appears to be `c_ulong `on SPARC and `c_uint` everywhere else.
 
 #[cfg(target_arch = "sparc")]
 pub type tcflag_t = ffi::c_ulong;

src/bitcast.rs

@@ -13,13 +13,13 @@ macro_rules! bitcast {
             0
         } else if false {
             // Ensure that the source and destinations are the same size.
-            // SAFETY: This code is under an `if false`.
             #[allow(
                 unsafe_code,
                 unused_unsafe,
                 clippy::useless_transmute,
                 clippy::missing_transmute_annotations
             )]
+            // SAFETY: This code is under an `if false`.
             unsafe {
                 ::core::mem::transmute($x)
             }

src/event/epoll.rs

@@ -107,11 +107,11 @@ pub fn create(flags: epoll::CreateFlags) -> io::Result<OwnedFd> {
 /// This registers interest in any of the events set in `event_flags` occurring
 /// on the file descriptor associated with `data`.
 ///
-/// Note that `close`ing a file descriptor does not necessarily unregister
-/// interest which can lead to spurious events being returned from
-/// [`epoll::wait`]. If a file descriptor is an `Arc<dyn SystemResource>`, then
-/// `epoll` can be thought to maintain a `Weak<dyn SystemResource>` to the file
-/// descriptor. Check the [faq] for details.
+/// `close`ing a file descriptor does not necessarily unregister interest which
+/// can lead to spurious events being returned from [`epoll::wait`]. If a file
+/// descriptor is an `Arc<dyn SystemResource>`, then `epoll` can be thought to
+/// maintain a `Weak<dyn SystemResource>` to the file descriptor. Check the
+/// [faq] for details.
 ///
 /// # References
 ///  - [Linux]
@@ -205,7 +205,8 @@ pub fn delete<EpollFd: AsFd, SourceFd: AsFd>(epoll: EpollFd, source: SourceFd) -
 /// [Linux]: https://man7.org/linux/man-pages/man2/epoll_wait.2.html
 /// [illumos]: https://www.illumos.org/man/3C/epoll_wait
 #[cfg(feature = "alloc")]
-#[cfg_attr(docsrs, doc(cfg(feature = "alloc"), alias = "epoll_wait"))]
+#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
+#[doc(alias = "epoll_wait")]
 #[inline]
 pub fn wait<EpollFd: AsFd>(
     epoll: EpollFd,

src/event/pause.rs

@@ -1,6 +1,6 @@
 use crate::backend;
 
-/// `pause()`
+/// `pause()`—Sleep until interrupted by a signal.
 ///
 /// The POSIX `pause` interface returns an error code, but the only thing
 /// `pause` does is sleep until interrupted by a signal, so it always

src/event/select.rs

@@ -96,7 +96,7 @@ pub struct FdSetElement(pub(crate) usize);
 ///
 /// # Safety
 ///
-/// All fds in in all the sets must correspond to open file descriptors.
+/// All fds in all the sets must correspond to open file descriptors.
 ///
 /// # References
 ///  - [POSIX]