Miscellaneous documentation cleanups. (bytecodealliance#967)

Author: sunfishcode

Cargo.toml

@@ -5,7 +5,7 @@ authors = [
     "Dan Gohman <dev@sunfishcode.online>",
     "Jakub Konka <kubkon@jakubkonka.com>",
 ]
-description = "Safe Rust bindings to POSIX/Unix/Linux/Winsock2-like syscalls"
+description = "Safe Rust bindings to POSIX/Unix/Linux/Winsock-like syscalls"
 documentation = "https://docs.rs/rustix"
 license = "Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT"
 repository = "https://github.com/bytecodealliance/rustix"
@@ -55,7 +55,7 @@ libc = { version = "0.2.150", default-features = false, features = ["extra_trait
 [target.'cfg(all(any(target_os = "android", target_os = "linux"), any(rustix_use_libc, miri, not(all(target_os = "linux", target_endian = "little", any(target_arch = "arm", all(target_arch = "aarch64", target_pointer_width = "64"), target_arch = "riscv64", all(rustix_use_experimental_asm, target_arch = "powerpc64"), all(rustix_use_experimental_asm, target_arch = "mips"), all(rustix_use_experimental_asm, target_arch = "mips32r6"), all(rustix_use_experimental_asm, target_arch = "mips64"), all(rustix_use_experimental_asm, target_arch = "mips64r6"), target_arch = "x86", all(target_arch = "x86_64", target_pointer_width = "64")))))))'.dependencies]
 linux-raw-sys = { version = "0.4.11", default-features = false, features = ["general", "ioctl", "no_std"] }
 
-# For the libc backend on Windows, use the Winsock2 API in windows-sys.
+# For the libc backend on Windows, use the Winsock API in windows-sys.
 [target.'cfg(windows)'.dependencies.windows-sys]
 version = "0.52.0"
 features = [

README.md

@@ -2,7 +2,7 @@
   <h1><code>rustix</code></h1>
 
   <p>
-    <strong>Safe Rust bindings to POSIX/Unix/Linux/Winsock2 syscalls</strong>
+    <strong>Safe Rust bindings to POSIX/Unix/Linux/Winsock syscalls</strong>
   </p>
 
   <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
@@ -16,17 +16,17 @@
 </div>
 
 `rustix` provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like,
-Unix-like, Linux, and Winsock2 syscall-like APIs, with configurable backends.
+Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends.
 It uses Rust references, slices, and return values instead of raw pointers, and
 [I/O safety types] instead of raw file descriptors, providing memory safety,
 [I/O safety], and [provenance]. It uses `Result`s for reporting errors,
 [`bitflags`] instead of bare integer flags, an [`Arg`] trait with optimizations
 to efficiently accept any Rust string type, and several other efficient
 conveniences.
 
-`rustix` is low-level and, and while the `net` API supports Winsock2 on
-Windows, the rest of the APIs do not support Windows; for higher-level and more
-portable APIs built on this functionality, see the [`cap-std`], [`memfd`],
+`rustix` is low-level and, and while the `net` API supports [Windows Sockets 2]
+(Winsock), the rest of the APIs do not support Windows; for higher-level and
+more portable APIs built on this functionality, see the [`cap-std`], [`memfd`],
 [`timerfd`], and [`io-streams`] crates, for example.
 
 `rustix` currently has two backends available:
@@ -42,7 +42,7 @@ portable APIs built on this functionality, see the [`cap-std`], [`memfd`],
       provenance all the way down to the syscalls.
 
  * libc, which uses the [`libc`] crate which provides bindings to native `libc`
-   libraries on Unix-family platforms, and [`windows-sys`] for Winsock2 on
+   libraries on Unix-family platforms, and [`windows-sys`] for Winsock on
    Windows, and is portable to many OS's.
 
 The linux_raw backend is enabled by default on platforms which support it. To
@@ -165,6 +165,7 @@ always reflect “very old” Linux versions.
 [any current Rust target]: https://doc.rust-lang.org/nightly/rustc/platform-support.html
 [kernel.org]: https://www.kernel.org/releases.html
 [Rust on Debian stable]: https://packages.debian.org/stable/rust/rustc
+[Windows Sockets 2]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-start-page-2
 [`nix`]: https://crates.io/crates/nix
 [`unix`]: https://crates.io/crates/unix
 [`nc`]: https://crates.io/crates/nc

src/backend/libc/fs/types.rs

@@ -159,13 +159,13 @@ bitflags! {
 #[cfg(not(target_os = "espidf"))]
 impl Mode {
     /// Construct a `Mode` from the mode bits of the `st_mode` field of a
-    /// `Stat`.
+    /// `Mode`.
     #[inline]
     pub const fn from_raw_mode(st_mode: RawMode) -> Self {
         Self::from_bits_truncate(st_mode)
     }
 
-    /// Construct an `st_mode` value from `Stat`.
+    /// Construct an `st_mode` value from a `Mode`.
     #[inline]
     pub const fn as_raw_mode(self) -> RawMode {
         self.bits()
@@ -503,7 +503,7 @@ impl FileType {
         }
     }
 
-    /// Construct an `st_mode` value from `Stat`.
+    /// Construct an `st_mode` value from a `FileType`.
     #[inline]
     pub const fn as_raw_mode(self) -> RawMode {
         match self {

src/backend/libc/io/errno.rs

@@ -14,7 +14,7 @@ use libc_errno::errno;
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
@@ -24,7 +24,7 @@ use libc_errno::errno;
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/errno.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/errno.3.html
-/// [Winsock2]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2
+/// [Winsock]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?errno
 /// [NetBSD]: https://man.netbsd.org/errno.2
 /// [OpenBSD]: https://man.openbsd.org/errno.2

src/backend/libc/mod.rs

@@ -1,7 +1,7 @@
 //! The libc backend.
 //!
 //! On most platforms, this uses the `libc` crate to make system calls. On
-//! Windows, this uses the Winsock2 API in `windows-sys`, which can be adapted
+//! Windows, this uses the Winsock API in `windows-sys`, which can be adapted
 //! to have a very `libc`-like interface.
 
 // Every FFI call requires an unsafe block, and there are a lot of FFI
@@ -21,11 +21,11 @@ pub(crate) mod fd {
     };
     pub(crate) use windows_sys::Win32::Networking::WinSock::SOCKET as LibcFd;
 
-    /// A version of [`AsRawFd`] for use with Winsock2 API.
+    /// A version of [`AsRawFd`] for use with Winsock API.
     ///
     /// [`AsRawFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsRawFd.html
     pub trait AsRawFd {
-        /// A version of [`as_raw_fd`] for use with Winsock2 API.
+        /// A version of [`as_raw_fd`] for use with Winsock API.
         ///
         /// [`as_raw_fd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.FromRawFd.html#tymethod.as_raw_fd
         fn as_raw_fd(&self) -> RawFd;
@@ -37,11 +37,11 @@ pub(crate) mod fd {
         }
     }
 
-    /// A version of [`IntoRawFd`] for use with Winsock2 API.
+    /// A version of [`IntoRawFd`] for use with Winsock API.
     ///
     /// [`IntoRawFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.IntoRawFd.html
     pub trait IntoRawFd {
-        /// A version of [`into_raw_fd`] for use with Winsock2 API.
+        /// A version of [`into_raw_fd`] for use with Winsock API.
         ///
         /// [`into_raw_fd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.FromRawFd.html#tymethod.into_raw_fd
         fn into_raw_fd(self) -> RawFd;
@@ -53,11 +53,11 @@ pub(crate) mod fd {
         }
     }
 
-    /// A version of [`FromRawFd`] for use with Winsock2 API.
+    /// A version of [`FromRawFd`] for use with Winsock API.
     ///
     /// [`FromRawFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.FromRawFd.html
     pub trait FromRawFd {
-        /// A version of [`from_raw_fd`] for use with Winsock2 API.
+        /// A version of [`from_raw_fd`] for use with Winsock API.
         ///
         /// # Safety
         ///
@@ -74,11 +74,11 @@ pub(crate) mod fd {
         }
     }
 
-    /// A version of [`AsFd`] for use with Winsock2 API.
+    /// A version of [`AsFd`] for use with Winsock API.
     ///
     /// [`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html
     pub trait AsFd {
-        /// An `as_fd` function for Winsock2, where a `Fd` is a `Socket`.
+        /// An `as_fd` function for Winsock, where a `Fd` is a `Socket`.
         fn as_fd(&self) -> BorrowedFd;
     }
     impl<T: AsSocket> AsFd for T {

src/backend/libc/mount/types.rs

@@ -227,7 +227,7 @@ bitflags! {
         /// `MOVE_MOUNT__MASK`
         const MOVE_MOUNT_SET_GROUP = 0x0000_0100;
 
-        // TODO: add when linux 6.5 is released
+        // TODO: add when Linux 6.5 is released
         // /// `MOVE_MOUNT_BENEATH`
         // const MOVE_MOUNT_BENEATH = 0x0000_0200;
 

src/backend/libc/pipe/types.rs

@@ -53,12 +53,14 @@ bitflags! {
     }
 }
 
-/// A buffer type used with `vmsplice`.
+/// A buffer type for use with [`vmsplice`].
 ///
 /// It is guaranteed to be ABI compatible with the iovec type on Unix platforms
 /// and `WSABUF` on Windows. Unlike `IoSlice` and `IoSliceMut` it is
 /// semantically like a raw pointer, and therefore can be shared or mutated as
 /// needed.
+///
+/// [`vmsplice`]: crate::pipe::vmsplice
 #[cfg(linux_kernel)]
 #[repr(transparent)]
 pub struct IoSliceRaw<'a> {

src/backend/libc/pty/syscalls.rs

@@ -58,7 +58,7 @@ pub(crate) fn ptsname(fd: BorrowedFd<'_>, mut buffer: Vec<u8>) -> io::Result<CSt
             }
         };
 
-        // MacOS 10.13.4 has `ptsname_r`; use it if we have it, otherwise fall
+        // macOS 10.13.4 has `ptsname_r`; use it if we have it, otherwise fall
         // back to calling the underlying ioctl directly.
         #[cfg(apple)]
         let r = unsafe {

src/backend/libc/winsock_c.rs

@@ -1,4 +1,4 @@
-//! Adapt the Winsock2 API to resemble a POSIX-style libc API.
+//! Adapt the Winsock API to resemble a POSIX-style libc API.
 
 #![allow(unused_imports)]
 #![allow(non_camel_case_types)]

src/backend/linux_raw/event/epoll.rs

@@ -1,4 +1,4 @@
-//! Linx `epoll` support.
+//! Linux `epoll` support.
 //!
 //! # Examples
 //!
@@ -160,8 +160,8 @@ pub fn create(flags: CreateFlags) -> io::Result<OwnedFd> {
     syscalls::epoll_create(flags)
 }
 
-/// `epoll_ctl(self, EPOLL_CTL_ADD, data, event)`—Adds an element to an
-/// epoll object.
+/// `epoll_ctl(self, EPOLL_CTL_ADD, data, event)`—Adds an element to an epoll
+/// object.
 ///
 /// This registers interest in any of the events set in `events` occurring on
 /// the file descriptor associated with `data`.

src/backend/linux_raw/fs/inotify.rs

@@ -107,7 +107,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     path.into_with_c_str(|path| syscalls::inotify_add_watch(inot, path, flags))
 }
 
-/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify
+/// `inotify_rm_watch(self, wd)`—Removes a watch from this inotify.
 ///
 /// The watch descriptor provided should have previously been returned by
 /// [`inotify_add_watch`] and not previously have been removed.

src/backend/linux_raw/fs/types.rs

@@ -127,13 +127,13 @@ bitflags! {
 
 impl Mode {
     /// Construct a `Mode` from the mode bits of the `st_mode` field of a
-    /// `Stat`.
+    /// `Mode`.
     #[inline]
     pub const fn from_raw_mode(st_mode: RawMode) -> Self {
         Self::from_bits_truncate(st_mode)
     }
 
-    /// Construct an `st_mode` value from `Stat`.
+    /// Construct an `st_mode` value from a `Mode`.
     #[inline]
     pub const fn as_raw_mode(self) -> RawMode {
         self.bits()
@@ -355,7 +355,7 @@ impl FileType {
         }
     }
 
-    /// Construct an `st_mode` value from `Stat`.
+    /// Construct an `st_mode` value from a `FileType`.
     #[inline]
     pub const fn as_raw_mode(self) -> RawMode {
         match self {

src/backend/linux_raw/io/errno.rs

@@ -24,7 +24,7 @@ use linux_raw_sys::errno;
 /// # References
 ///  - [POSIX]
 ///  - [Linux]
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
@@ -34,7 +34,7 @@ use linux_raw_sys::errno;
 ///
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/errno.html
 /// [Linux]: https://man7.org/linux/man-pages/man3/errno.3.html
-/// [Winsock2]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2
+/// [Winsock]: https://learn.microsoft.com/en-us/windows/win32/winsock/windows-sockets-error-codes-2
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?errno
 /// [NetBSD]: https://man.netbsd.org/errno.2
 /// [OpenBSD]: https://man.openbsd.org/errno.2

src/backend/linux_raw/mount/types.rs

@@ -223,7 +223,7 @@ bitflags! {
         /// `MOVE_MOUNT__MASK`
         const MOVE_MOUNT_SET_GROUP = linux_raw_sys::general::MOVE_MOUNT_SET_GROUP;
 
-        // TODO: add when linux 6.5 is released
+        // TODO: add when Linux 6.5 is released
         // /// `MOVE_MOUNT_BENEATH`
         // const MOVE_MOUNT_BENEATH = linux_raw_sys::general::MOVE_MOUNT_BENEATH;
 

src/backend/linux_raw/pipe/types.rs

@@ -22,7 +22,7 @@ bitflags! {
 }
 
 bitflags! {
-    /// `SPLICE_F_*` constants for use with [`splice`] [`vmsplice`], and
+    /// `SPLICE_F_*` constants for use with [`splice`], [`vmsplice`], and
     /// [`tee`].
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
@@ -41,12 +41,14 @@ bitflags! {
     }
 }
 
-/// A buffer type used with `vmsplice`.
+/// A buffer type for use with [`vmsplice`].
 ///
 /// It is guaranteed to be ABI compatible with the iovec type on Unix platforms
 /// and `WSABUF` on Windows. Unlike `IoSlice` and `IoSliceMut` it is
 /// semantically like a raw pointer, and therefore can be shared or mutated as
 /// needed.
+///
+/// [`vmsplice`]: crate::pipe::vmsplice
 #[repr(transparent)]
 pub struct IoSliceRaw<'a> {
     _buf: c::iovec,

src/event/kqueue.rs

@@ -13,7 +13,7 @@ use core::mem::zeroed;
 use core::ptr::slice_from_raw_parts_mut;
 use core::time::Duration;
 
-/// A `kqueue` event.
+/// A `kqueue` event for use with [`kevent`].
 #[repr(transparent)]
 #[derive(Copy, Clone)]
 pub struct Event {

src/event/poll.rs

@@ -9,7 +9,7 @@ pub use backend::event::poll_fd::{PollFd, PollFlags};
 ///  - [POSIX]
 ///  - [Linux]
 ///  - [Apple]
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
@@ -20,7 +20,7 @@ pub use backend::event::poll_fd::{PollFd, PollFlags};
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html
 /// [Linux]: https://man7.org/linux/man-pages/man2/poll.2.html
 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/poll.2.html
-/// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll
+/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=poll&sektion=2
 /// [NetBSD]: https://man.netbsd.org/poll.2
 /// [OpenBSD]: https://man.openbsd.org/poll.2

src/io/close.rs

@@ -25,7 +25,7 @@ use backend::fd::RawFd;
 ///  - [POSIX]
 ///  - [Linux]
 ///  - [Apple]
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
@@ -37,7 +37,7 @@ use backend::fd::RawFd;
 /// [POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
 /// [Linux]: https://man7.org/linux/man-pages/man2/close.2.html
 /// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/close.2.html#//apple_ref/doc/man/2/close
-/// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
+/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=close&sektion=2
 /// [NetBSD]: https://man.netbsd.org/close.2
 /// [OpenBSD]: https://man.openbsd.org/close.2

src/io/ioctl.rs

@@ -31,11 +31,11 @@ pub fn ioctl_fioclex<Fd: AsFd>(fd: Fd) -> io::Result<()> {
 /// `ioctl(fd, FIONBIO, &value)`—Enables or disables non-blocking mode.
 ///
 /// # References
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [NetBSD]
 ///  - [OpenBSD]
 ///
-/// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/winsock/winsock-ioctls#unix-ioctl-codes
+/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/winsock/winsock-ioctls#unix-ioctl-codes
 /// [NetBSD]: https://man.netbsd.org/ioctl.2#GENERIC%20IOCTLS
 /// [OpenBSD]: https://man.openbsd.org/ioctl.2#GENERIC_IOCTLS
 #[inline]
@@ -55,13 +55,13 @@ pub fn ioctl_fionbio<Fd: AsFd>(fd: Fd, value: bool) -> io::Result<()> {
 ///
 /// # References
 ///  - [Linux]
-///  - [Winsock2]
+///  - [Winsock]
 ///  - [FreeBSD]
 ///  - [NetBSD]
 ///  - [OpenBSD]
 ///
 /// [Linux]: https://man7.org/linux/man-pages/man2/ioctl_tty.2.html
-/// [Winsock2]: https://docs.microsoft.com/en-us/windows/win32/winsock/winsock-ioctls#unix-ioctl-codes
+/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/winsock/winsock-ioctls#unix-ioctl-codes
 /// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=ioctl&sektion=2#GENERIC%09IOCTLS
 /// [NetBSD]: https://man.netbsd.org/ioctl.2#GENERIC%20IOCTLS
 /// [OpenBSD]: https://man.openbsd.org/ioctl.2#GENERIC_IOCTLS