Miscellaneous documentation fixes. (#1129)

Author: sunfishcode

Cargo.toml

@@ -182,8 +182,8 @@ stdio = []
 # Enable `rustix::system::*`.
 system = ["linux-raw-sys/system"]
 
-# Enable `rustix::runtime::*`. This API is undocumented and unstable and
-# experimental and not intended for general-purpose use.
+# Enable `rustix::runtime::*`. ⚠ This API is undocumented and unstable and
+# experimental and not intended for general-purpose use. ⚠
 runtime = ["linux-raw-sys/prctl"]
 
 # Enable all API features.

src/backend/libc/c.rs

@@ -86,8 +86,9 @@ pub(crate) const XCASE: tcflag_t = linux_raw_sys::general::XCASE as _;
 #[cfg(target_os = "aix")]
 pub(crate) const MSG_DONTWAIT: c_int = libc::MSG_NONBLOCK;
 
-// It is defined as 0 in libc under 64-bit platforms, but is automatically set
-// by kernel. <https://github.com/torvalds/linux/blob/v6.7/fs/open.c#L1458-L1459>
+// `O_LARGEFILE` can be automatically set by the kernel on Linux:
+// <https://github.com/torvalds/linux/blob/v6.7/fs/open.c#L1458-L1459>
+// so libc implementations may leave it undefined or defined to zero.
 #[cfg(linux_kernel)]
 pub(crate) const O_LARGEFILE: c_int = linux_raw_sys::general::O_LARGEFILE as _;
 

src/backend/libc/event/epoll.rs

@@ -85,7 +85,7 @@ use core::ptr::null_mut;
 use core::slice;
 
 bitflags! {
-    /// `EPOLL_*` for use with [`new`].
+    /// `EPOLL_*` for use with [`create`].
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct CreateFlags: u32 {
@@ -157,6 +157,11 @@ bitflags! {
 ///
 /// Use the [`CreateFlags::CLOEXEC`] flag to prevent the resulting file
 /// descriptor from being implicitly passed across `exec` boundaries.
+///
+/// # References
+///  - [Linux]
+///
+/// [Linux]: https://man7.org/linux/man-pages/man2/epoll_create.2.html
 #[inline]
 #[doc(alias = "epoll_create1")]
 pub fn create(flags: CreateFlags) -> io::Result<OwnedFd> {
@@ -171,12 +176,17 @@ pub fn create(flags: CreateFlags) -> io::Result<OwnedFd> {
 /// This registers interest in any of the events set in `events` occurring on
 /// the file descriptor associated with `data`.
 ///
-/// If [`delete`] is not called on the I/O source passed into this function
-/// before the I/O source is `close`d, then the `epoll` will act as if the I/O
-/// source is still registered with it. This can lead to spurious events being
-/// returned from [`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.
+/// Note that `close`ing a file descriptor does not necessarily unregister
+/// interest which can lead to spurious events being returned from [`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]
+///
+/// [Linux]: https://man7.org/linux/man-pages/man2/epoll_ctl.2.html
+/// [faq]: https://man7.org/linux/man-pages/man7/epoll.7.html#:~:text=Will%20closing%20a%20file%20descriptor%20cause%20it%20to%20be%20removed%20from%20all%0A%20%20%20%20%20%20%20%20%20%20epoll%20interest%20lists%3F
 #[doc(alias = "epoll_ctl")]
 pub fn add(
     epoll: impl AsFd,
@@ -209,6 +219,11 @@ pub fn add(
 /// given epoll object.
 ///
 /// This sets the events of interest with `target` to `events`.
+///
+/// # References
+///  - [Linux]
+///
+/// [Linux]: https://man7.org/linux/man-pages/man2/epoll_ctl.2.html
 #[doc(alias = "epoll_ctl")]
 pub fn modify(
     epoll: impl AsFd,
@@ -240,6 +255,11 @@ pub fn modify(
 
 /// `epoll_ctl(self, EPOLL_CTL_DEL, target, NULL)`—Removes an element in a
 /// given epoll object.
+///
+/// # References
+///  - [Linux]
+///
+/// [Linux]: https://man7.org/linux/man-pages/man2/epoll_ctl.2.html
 #[doc(alias = "epoll_ctl")]
 pub fn delete(epoll: impl AsFd, source: impl AsFd) -> io::Result<()> {
     // SAFETY: We're calling `epoll_ctl` via FFI and we know how it
@@ -260,6 +280,11 @@ pub fn delete(epoll: impl AsFd, source: impl AsFd) -> io::Result<()> {
 ///
 /// For each event of interest, an element is written to `events`. On
 /// success, this returns the number of written elements.
+///
+/// # References
+///  - [Linux]
+///
+/// [Linux]: https://man7.org/linux/man-pages/man2/epoll_wait.2.html
 #[cfg(feature = "alloc")]
 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
 pub fn wait(epoll: impl AsFd, event_list: &mut EventVec, timeout: c::c_int) -> io::Result<()> {

src/backend/libc/fs/syscalls.rs

@@ -348,7 +348,7 @@ pub(crate) fn linkat(
     new_path: &CStr,
     flags: AtFlags,
 ) -> io::Result<()> {
-    // macOS <= 10.9 lacks `linkat`.
+    // macOS ≤ 10.9 lacks `linkat`.
     #[cfg(target_os = "macos")]
     unsafe {
         weak! {
@@ -405,7 +405,7 @@ pub(crate) fn unlink(path: &CStr) -> io::Result<()> {
 
 #[cfg(not(any(target_os = "espidf", target_os = "redox")))]
 pub(crate) fn unlinkat(dirfd: BorrowedFd<'_>, path: &CStr, flags: AtFlags) -> io::Result<()> {
-    // macOS <= 10.9 lacks `unlinkat`.
+    // macOS ≤ 10.9 lacks `unlinkat`.
     #[cfg(target_os = "macos")]
     unsafe {
         weak! {
@@ -458,7 +458,7 @@ pub(crate) fn renameat(
     new_dirfd: BorrowedFd<'_>,
     new_path: &CStr,
 ) -> io::Result<()> {
-    // macOS <= 10.9 lacks `renameat`.
+    // macOS ≤ 10.9 lacks `renameat`.
     #[cfg(target_os = "macos")]
     unsafe {
         weak! {
@@ -744,7 +744,7 @@ pub(crate) fn accessat(
     access: Access,
     flags: AtFlags,
 ) -> io::Result<()> {
-    // macOS <= 10.9 lacks `faccessat`.
+    // macOS ≤ 10.9 lacks `faccessat`.
     #[cfg(target_os = "macos")]
     unsafe {
         weak! {
@@ -2255,8 +2255,8 @@ pub(crate) fn getxattr(path: &CStr, name: &CStr, value: &mut [u8]) -> io::Result
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
-        // null instead.
+        // Passing an empty to slice to `getxattr` leads to `ERANGE` on macOS.
+        // Pass null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {
@@ -2291,8 +2291,8 @@ pub(crate) fn lgetxattr(path: &CStr, name: &CStr, value: &mut [u8]) -> io::Resul
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
-        // null instead.
+        // Passing an empty to slice to `getxattr` leads to `ERANGE` on macOS.
+        // Pass null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {
@@ -2328,8 +2328,8 @@ pub(crate) fn fgetxattr(fd: BorrowedFd<'_>, name: &CStr, value: &mut [u8]) -> io
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
-        // null instead.
+        // Passing an empty to slice to `getxattr` leads to `ERANGE` on macOS.
+        // Pass null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {

src/backend/libc/io/errno.rs

@@ -31,7 +31,6 @@ use libc_errno::errno;
 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=errno&section=2
 /// [illumos]: https://illumos.org/man/3C/errno
 /// [glibc]: https://www.gnu.org/software/libc/manual/html_node/Error-Codes.html
-/// [`std::io::Error`]: Result
 #[repr(transparent)]
 #[doc(alias = "errno")]
 #[derive(Eq, PartialEq, Hash, Copy, Clone)]

src/backend/libc/net/netdevice.rs

@@ -1,3 +1,5 @@
+//! Wrappers for netdevice ioctls.
+
 #![allow(unsafe_code)]
 
 #[cfg(feature = "alloc")]

src/backend/libc/net/send_recv.rs

@@ -2,7 +2,7 @@ use crate::backend::c;
 use bitflags::bitflags;
 
 bitflags! {
-    /// `MSG_*` flags for use with [`send`], [`send_to`], and related
+    /// `MSG_*` flags for use with [`send`], [`sendto`], and related
     /// functions.
     ///
     /// [`send`]: crate::net::send
@@ -29,6 +29,8 @@ bitflags! {
         #[cfg(not(windows))]
         const DONTWAIT = bitcast!(c::MSG_DONTWAIT);
         /// Deprecated alias for [`EOR`].
+        ///
+        /// [`EOR`]: Self::EOR
         #[cfg(not(windows))]
         #[deprecated(note = "`rustix::net::SendFlags::EOT` is renamed to `rustix::net::SendFlags::EOR`.")]
         const EOT = bitcast!(c::MSG_EOR);

src/backend/libc/net/syscalls.rs

@@ -526,8 +526,8 @@ pub(crate) fn acceptfrom_with(
     }
 }
 
-/// Darwin lacks `accept4`, but does have `accept`. We define
-/// `SocketFlags` to have no flags, so we can discard it here.
+/// Darwin lacks `accept4`, but does have `accept`. We define `SocketFlags` to
+/// have no flags, so we can discard it here.
 #[cfg(any(
     apple,
     windows,
@@ -541,8 +541,8 @@ pub(crate) fn accept_with(sockfd: BorrowedFd<'_>, _flags: SocketFlags) -> io::Re
     accept(sockfd)
 }
 
-/// Darwin lacks `accept4`, but does have `accept`. We define
-/// `SocketFlags` to have no flags, so we can discard it here.
+/// Darwin lacks `accept4`, but does have `accept`. We define `SocketFlags` to
+/// have no flags, so we can discard it here.
 #[cfg(any(
     apple,
     windows,

src/backend/libc/process/syscalls.rs

@@ -585,8 +585,8 @@ fn _waitid_pidfd(fd: BorrowedFd<'_>, options: WaitidOptions) -> io::Result<Optio
 unsafe fn cvt_waitid_status(status: MaybeUninit<c::siginfo_t>) -> Option<WaitidStatus> {
     let status = status.assume_init();
     // `si_pid` is supposedly the better way to check that the struct has been
-    // filled, e.g. the Linux manpage says about the `WNOHANG` case “zero out
-    // the si_pid field before the call and check for a nonzero value”.
+    // filled, e.g. the Linux manual page says about the `WNOHANG` case “zero
+    // out the si_pid field before the call and check for a nonzero value”.
     // But e.g. NetBSD/OpenBSD don't have it exposed in the libc crate for now,
     // and some platforms don't have it at all. For simplicity, always check
     // `si_signo`. We have zero-initialized the whole struct, and all kernels

src/backend/libc/termios/syscalls.rs

@@ -117,7 +117,7 @@ pub(crate) fn tcgetpgrp(fd: BorrowedFd<'_>) -> io::Result<Pid> {
         let pid = ret_pid_t(c::tcgetpgrp(borrowed_fd(fd)))?;
 
         // This doesn't appear to be documented, but on Linux, it appears
-        // `tcsetpgrp` can succceed and set the pid to 0 if we pass it a
+        // `tcsetpgrp` can succeed and set the pid to 0 if we pass it a
         // pseudo-terminal device fd. For now, translate it into `OPNOTSUPP`.
         #[cfg(linux_kernel)]
         if pid == 0 {