Miscellaneous documentaion cleanups. (#1421)

 - Use `1` instead of `1.0.0` in documentation links in CHANGES.md.
 - Add more links to platform documentation.
 - Minor comment cleanups.

Author: sunfishcode

CHANGES.md

@@ -14,8 +14,8 @@ cargo test --features=all-apis
 ```
 
 And, rustix has two backends, linux_raw and libc, and only one is used in
-any given build. To test with the libc backend explicitly, additionally
-enable the `use-libc` feature:
+any given build. To test on Linux with the libc backend explicitly,
+additionally enable the `use-libc` feature:
 
 ```console
 cargo test --features=all-apis,use-libc

CONTRIBUTING.md

@@ -56,8 +56,8 @@ pub(in crate::backend) mod asm;
 pub(in crate::backend) use self::asm as choose;
 
 // On 32-bit x86, use vDSO wrappers for all syscalls. We could use the
-// architecture syscall instruction (`int 0x80`), but the vDSO kernel_vsyscall
-// mechanism is much faster.
+// architecture syscall instruction (`int 0x80`), but the vDSO
+// `__kernel_vsyscall` mechanism is much faster.
 #[cfg(target_arch = "x86")]
 pub(in crate::backend) use super::vdso_wrappers::x86_via_vdso as choose;
 

src/backend/linux_raw/arch/mod.rs

@@ -261,7 +261,7 @@ fn duration_from_linux_sock_timeval(time: __kernel_sock_timeval) -> Option<Durat
     }
 }
 
-/// Like `duration_from_linux` but uses Linux's old 32-bit
+/// Like `duration_from_linux_sock_timeval` but uses Linux's old 32-bit
 /// `__kernel_old_timeval`.
 fn duration_from_linux_old_timeval(time: __kernel_old_timeval) -> Option<Duration> {
     if time.tv_sec == 0 && time.tv_usec == 0 {
@@ -297,7 +297,7 @@ fn duration_to_linux_sock_timeval(timeout: Option<Duration>) -> io::Result<__ker
     })
 }
 
-/// Like `duration_to_linux` but uses Linux's old 32-bit
+/// Like `duration_to_linux_sock_timeval` but uses Linux's old 32-bit
 /// `__kernel_old_timeval`.
 fn duration_to_linux_old_timeval(timeout: Option<Duration>) -> io::Result<__kernel_old_timeval> {
     Ok(match timeout {

src/backend/linux_raw/net/sockopt.rs

@@ -282,7 +282,7 @@ fn maybe_init_auxv() {
 /// /proc/self/auxv for kernels that don't support `PR_GET_AUXV`.
 #[cold]
 fn init_auxv_impl() -> Result<(), ()> {
-    // 512 AUX elements ought to be enough for anybody…
+    // 512 bytes of AUX elements ought to be enough for anybody…
     let mut buffer = [0_u8; 512];
 
     // If we don't have "alloc", just try to read into our statically-sized

src/backend/linux_raw/param/auxv.rs

@@ -1,4 +1,4 @@
-//! Utilities to help with buffering.
+//! Utilities for functions that return data via buffers.
 
 #![allow(unsafe_code)]
 
@@ -22,7 +22,7 @@ use core::slice;
 ///
 /// Passing a `&mut [u8]`:
 ///
-/// ```rust
+/// ```
 /// # use rustix::io::read;
 /// # fn example(fd: rustix::fd::BorrowedFd) -> rustix::io::Result<()> {
 /// let mut buf = [0_u8; 64];
@@ -34,7 +34,7 @@ use core::slice;
 ///
 /// Passing a `&mut [MaybeUninit<u8>]`:
 ///
-/// ```rust
+/// ```
 /// # use rustix::io::read;
 /// # use std::mem::MaybeUninit;
 /// # fn example(fd: rustix::fd::BorrowedFd) -> rustix::io::Result<()> {
@@ -48,7 +48,7 @@ use core::slice;
 ///
 /// Passing a [`SpareCapacity`], via the [`spare_capacity`] helper function:
 ///
-/// ```rust
+/// ```
 /// # use rustix::io::read;
 /// # use rustix::buffer::spare_capacity;
 /// # fn example(fd: rustix::fd::BorrowedFd) -> rustix::io::Result<()> {
@@ -293,7 +293,8 @@ mod private {
 
         /// Return a pointer and length for this buffer.
         ///
-        /// The length is the number of elements of type `T`, not a number of bytes.
+        /// The length is the number of elements of type `T`, not a number of
+        /// bytes.
         ///
         /// It's tempting to have this return `&mut [MaybeUninit<T>]` instead,
         /// however that would require this function to be `unsafe`, because
@@ -370,7 +371,10 @@ mod tests {
         let mut buf = [0_u8; 64];
         let nread = read(&input, &mut buf).unwrap();
         assert_eq!(nread, buf.len());
-        assert_eq!(&buf[..38], b"//! Utilities to help with buffering.\n");
+        assert_eq!(
+            &buf[..58],
+            b"//! Utilities for functions that return data via buffers.\n"
+        );
         input.seek(SeekFrom::End(-1)).unwrap();
         let nread = read(&input, &mut buf).unwrap();
         assert_eq!(nread, 1);
@@ -393,11 +397,14 @@ mod tests {
         let mut buf = [MaybeUninit::<u8>::uninit(); 64];
         let (init, uninit) = read(&input, &mut buf).unwrap();
         assert_eq!(uninit.len(), 0);
-        assert_eq!(&init[..38], b"//! Utilities to help with buffering.\n");
+        assert_eq!(
+            &init[..58],
+            b"//! Utilities for functions that return data via buffers.\n"
+        );
         assert_eq!(init.len(), buf.len());
         assert_eq!(
-            unsafe { core::mem::transmute::<&mut [MaybeUninit<u8>], &mut [u8]>(&mut buf[..38]) },
-            b"//! Utilities to help with buffering.\n"
+            unsafe { core::mem::transmute::<&mut [MaybeUninit<u8>], &mut [u8]>(&mut buf[..58]) },
+            b"//! Utilities for functions that return data via buffers.\n"
         );
         input.seek(SeekFrom::End(-1)).unwrap();
         let (init, uninit) = read(&input, &mut buf).unwrap();
@@ -423,7 +430,10 @@ mod tests {
         let nread = read(&input, spare_capacity(&mut buf)).unwrap();
         assert_eq!(nread, buf.capacity());
         assert_eq!(nread, buf.len());
-        assert_eq!(&buf[..38], b"//! Utilities to help with buffering.\n");
+        assert_eq!(
+            &buf[..58],
+            b"//! Utilities for functions that return data via buffers.\n"
+        );
         buf.clear();
         input.seek(SeekFrom::End(-1)).unwrap();
         let nread = read(&input, spare_capacity(&mut buf)).unwrap();

src/buffer.rs

@@ -5,7 +5,10 @@
 /// strings, and passing strings to rustix as `CStr`s means that rustix doesn't
 /// need to copy them into a separate buffer to NUL-terminate them.
 ///
+/// In Rust ≥ 1.77, users can use [C-string literals] instead of this macro.
+///
 /// [`CStr`]: crate::ffi::CStr
+/// [C-string literals]: https://blog.rust-lang.org/2024/03/21/Rust-1.77.0.html#c-string-literals
 ///
 /// # Examples
 ///

src/cstr.rs

@@ -3,8 +3,8 @@ use crate::backend;
 /// `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
-/// returns the same thing with the same error code, so in rustix, the
+/// `pause` does is sleep until interrupted by a signal. If it were exposed in
+/// the API here it would always return `Errno::INTR`, so for simplicity the
 /// return value is omitted.
 ///
 /// # References

src/event/pause.rs

@@ -4,6 +4,10 @@ use backend::fs::types::MemfdFlags;
 
 /// `memfd_create(name, flags)`—Create an anonymous file.
 ///
+/// For a higher-level API to this functionality, see the [memfd] crate.
+///
+/// [memfd]: https://crates.io/crates/memfd
+///
 /// # References
 ///  - [Linux]
 ///  - [glibc]

src/fs/memfd_create.rs

@@ -27,10 +27,16 @@ bitflags! {
 
 /// `getxattr(path, name, value)`—Get extended filesystem attributes.
 ///
+/// For a higher-level API to xattr functionality, see the [xattr] crate.
+///
+/// [xattr]: https://crates.io/crates/xattr
+///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/getxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getxattr.2.html
 #[inline]
 pub fn getxattr<P: path::Arg, Name: path::Arg, Buf: Buffer<u8>>(
     path: P,
@@ -76,8 +82,10 @@ pub fn lgetxattr<P: path::Arg, Name: path::Arg, Buf: Buffer<u8>>(
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/fgetxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fgetxattr.2.html
 #[inline]
 pub fn fgetxattr<Fd: AsFd, Name: path::Arg, Buf: Buffer<u8>>(
     fd: Fd,
@@ -97,8 +105,10 @@ pub fn fgetxattr<Fd: AsFd, Name: path::Arg, Buf: Buffer<u8>>(
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/setxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/setxattr.2.html
 #[inline]
 pub fn setxattr<P: path::Arg, Name: path::Arg>(
     path: P,
@@ -136,8 +146,10 @@ pub fn lsetxattr<P: path::Arg, Name: path::Arg>(
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/fsetxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fsetxattr.2.html
 #[inline]
 pub fn fsetxattr<Fd: AsFd, Name: path::Arg>(
     fd: Fd,
@@ -155,6 +167,7 @@ pub fn fsetxattr<Fd: AsFd, Name: path::Arg>(
 ///  - [Linux]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/listxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/listxattr.2.html
 #[inline]
 pub fn listxattr<P: path::Arg, Buf: Buffer<u8>>(path: P, mut list: Buf) -> io::Result<Buf::Output> {
     path.into_with_c_str(|path| {
@@ -190,8 +203,10 @@ pub fn llistxattr<P: path::Arg, Buf: Buffer<u8>>(
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/flistxattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/flistxattr.2.html
 #[inline]
 pub fn flistxattr<Fd: AsFd, Buf: Buffer<u8>>(fd: Fd, mut list: Buf) -> io::Result<Buf::Output> {
     // SAFETY: `flistxattr` behaves.
@@ -204,8 +219,10 @@ pub fn flistxattr<Fd: AsFd, Buf: Buffer<u8>>(fd: Fd, mut list: Buf) -> io::Resul
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/removexattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/removexattr.2.html
 pub fn removexattr<P: path::Arg, Name: path::Arg>(path: P, name: Name) -> io::Result<()> {
     path.into_with_c_str(|path| {
         name.into_with_c_str(|name| backend::fs::syscalls::removexattr(path, name))
@@ -230,8 +247,10 @@ pub fn lremovexattr<P: path::Arg, Name: path::Arg>(path: P, name: Name) -> io::R
 ///
 /// # References
 ///  - [Linux]
+///  - [Apple]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/fremovexattr.2.html
+/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fremovexattr.2.html
 pub fn fremovexattr<Fd: AsFd, Name: path::Arg>(fd: Fd, name: Name) -> io::Result<()> {
     name.into_with_c_str(|name| backend::fs::syscalls::fremovexattr(fd.as_fd(), name))
 }

src/fs/xattr.rs

@@ -2012,7 +2012,7 @@ mod tests {
         assert_eq_align!(io_uring_user_data, u64);
 
         // Test that `u64`s and pointers are properly stored in
-        // io_uring_user_data`.
+        // `io_uring_user_data`.
         unsafe {
             const MAGIC: u64 = !0x0123_4567_89ab_cdef;
             let user_data = io_uring_user_data::from_u64(MAGIC);

src/io_uring/mod.rs

@@ -411,7 +411,7 @@ pub fn mlockall(flags: MlockAllFlags) -> io::Result<()> {
 
 /// Unlocks all pages mapped into the address space of the calling process.
 ///
-/// # Warnings
+/// # Warning
 ///
 /// This function is aware of all the memory pages in the process, as if it
 /// were a debugger. It unlocks all the pages, which could potentially

src/mm/mmap.rs

@@ -143,7 +143,8 @@ pub enum SendAncillaryMessage<'slice, 'fd> {
 impl SendAncillaryMessage<'_, '_> {
     /// Get the maximum size of an ancillary message.
     ///
-    /// This can be helpful in determining the size of the buffer you allocate.
+    /// This can be used to determine the size of the buffer to allocate for a
+    /// [`SendAncillaryBuffer::new`] with one message.
     pub const fn size(&self) -> usize {
         match self {
             Self::ScmRights(slice) => cmsg_space!(ScmRights(slice.len())),

src/net/send_recv/msg.rs

@@ -14,8 +14,8 @@ use crate::backend;
 /// # Safety
 ///
 /// This must be passed a pointer to the original environment variable block
-/// set up by the OS at process startup, and it must be called before any
-/// other rustix functions are called.
+/// set up by the OS at process startup, and it must be called before any other
+/// rustix functions are called.
 #[inline]
 #[doc(hidden)]
 pub unsafe fn init(envp: *mut *mut u8) {

src/param/init.rs

@@ -80,7 +80,7 @@ impl Pid {
         }
     }
 
-    /// Test whether this pid represents the init process (pid 1).
+    /// Test whether this pid represents the init process ([`Pid::INIT`]).
     #[inline]
     pub const fn is_init(self) -> bool {
         self.0.get() == Self::INIT.0.get()