Miscellaneous documentaion cleanups.

CHANGES.md

@@ -46,7 +46,7 @@ constant.
 `rustix::process::WaitidOptions` and `rustix::process::WaitidStatus` are
 renamed to
 [`rustix::process::WaitIdOptions`] and [`rustix::process::WaitIdStatus`] (note
-the capitalization), for consistency with [`crate::process::WaitId`].
+the capitalization), for consistency with [`rustix::process::WaitId`].
 
 [`rustix::process::WaitIdOptions`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.WaitIdOptions.html
 [`rustix::process::WaitIdStatus`]: https://docs.rs/rustix/1.0.0/rustix/process/struct.WaitIdStatus.html
@@ -198,7 +198,7 @@ be used in place of `mount2`, and `mount2` is now removed.
 The [`rustix::net`] functions ending with `_v4`, `_v6`, `_unix` and `_xdp` have
 been merged into a single function that accepts any address type.
 
-Specically, the following functions are removed:
+Specifically, the following functions are removed:
 
   * `bind_any`, `bind_unix`, `bind_v4`, `bind_v6`, `bind_xdp` in favor of
     [`bind`],

src/backend/libc/c.rs

@@ -87,7 +87,7 @@ pub(crate) const XCASE: tcflag_t = linux_raw_sys::general::XCASE as _;
 pub(crate) const MSG_DONTWAIT: c_int = MSG_NONBLOCK;
 
 // `O_LARGEFILE` can be automatically set by the kernel on Linux:
-// <https://github.com/torvalds/linux/blob/v6.7/fs/open.c#L1458-L1459>
+// <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/fs/open.c?h=v6.13#n1423>
 // 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/syscalls.rs

@@ -575,7 +575,7 @@ pub(crate) fn epoll_wait(
         .map(|i| i as usize)
     }
 
-    // Othewise just use `epoll_wait`.
+    // Otherwise just use `epoll_wait`.
     #[cfg(not(all(linux_kernel, feature = "linux_5_11")))]
     unsafe {
         let timeout = match timeout {

src/backend/libc/fs/dir.rs

@@ -137,11 +137,11 @@ impl Dir {
 
     /// `seekdir(self, offset)`
     ///
-    /// This function iso only available on 64-bit platforms because it's
+    /// This function is only available on 64-bit platforms because it's
     /// implemented using [`libc::seekdir`] which only supports offsets that
     /// fit in a `c_long`.
     ///
-    /// [`libc::seekdir`]: https://docs.rs/libc/latest/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html
+    /// [`libc::seekdir`]: https://docs.rs/libc/*/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html
     #[cfg(target_pointer_width = "64")]
     #[cfg_attr(docsrs, doc(cfg(target_pointer_width = "64")))]
     #[doc(alias = "seekdir")]

src/backend/libc/fs/syscalls.rs

@@ -1251,9 +1251,9 @@ pub(crate) fn fadvise(
         }
     }
 
-    // Similarly, on FreeBSD, if `offset + len` would overflow an `off_t` in
-    // a way that users using a `u64` interface wouldn't be aware of, reduce
-    // the length so that we only operate on the range that doesn't overflow.
+    // Similarly, on FreeBSD, if `offset + len` would overflow an `off_t` in a
+    // way that users using a `u64` interface wouldn't be aware of, reduce the
+    // length so that we only operate on the range that doesn't overflow.
     #[cfg(target_os = "freebsd")]
     let len = if len > 0 && offset.checked_add(len).is_none() {
         i64::MAX - offset

src/backend/libc/net/addr.rs

@@ -236,17 +236,18 @@ impl fmt::Debug for SocketAddrUnix {
     }
 }
 
-/// `struct sockaddr_storage`.
+/// `struct sockaddr_storage`
 ///
 /// This type is guaranteed to be large enough to hold any encoded socket
 /// address.
 #[repr(transparent)]
 #[derive(Copy, Clone)]
+#[doc(alias = "sockaddr_storage")]
 pub struct SocketAddrStorage(c::sockaddr_storage);
 
 impl SocketAddrStorage {
     /// Return a socket addr storage initialized to all zero bytes. The
-    /// `sa_family` is set to `AddressFamily::UNSPEC`.
+    /// `sa_family` is set to [`AddressFamily::UNSPEC`].
     pub fn zeroed() -> Self {
         assert_eq!(c::AF_UNSPEC, 0);
         // SAFETY: `sockaddr_storage` is meant to be zero-initializable.
@@ -264,7 +265,7 @@ impl SocketAddrStorage {
     }
 
     /// Clear the `sa_family` of this socket address to
-    /// `AddressFamily::UNSPEC`.
+    /// [`AddressFamily::UNSPEC`].
     pub fn clear_family(&mut self) {
         // SAFETY: `self.0` is a `sockaddr_storage` so it has enough space.
         unsafe {

src/backend/linux_raw/fs/dir.rs

@@ -81,11 +81,11 @@ impl Dir {
 
     /// `seekdir(self, offset)`
     ///
-    /// This function iso only available on 64-bit platforms because it's
+    /// This function is only available on 64-bit platforms because it's
     /// implemented using [`libc::seekdir`] which only supports offsets that
     /// fit in a `c_long`.
     ///
-    /// [`libc::seekdir`]: https://docs.rs/libc/latest/arm-unknown-linux-gnueabihf/libc/fn.seekdir.html
+    /// [`libc::seekdir`]: https://docs.rs/libc/*/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 limitation, but it's a goal of rustix to support the same API
     // on both the linux_raw and libc backends.

src/backend/linux_raw/fs/syscalls.rs

@@ -287,7 +287,7 @@ pub(crate) fn tell(fd: BorrowedFd<'_>) -> io::Result<u64> {
 
 #[inline]
 pub(crate) fn ftruncate(fd: BorrowedFd<'_>, length: u64) -> io::Result<()> {
-    // <https://github.com/torvalds/linux/blob/fcadab740480e0e0e9fa9bd272acd409884d431a/arch/arm64/kernel/sys32.c#L81-L83>
+    // <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/kernel/sys32.c?h=v6.13#n89>
     #[cfg(all(
         target_pointer_width = "32",
         any(

src/backend/linux_raw/fs/types.rs

@@ -197,13 +197,13 @@ bitflags! {
         /// `O_DIRECTORY`
         const DIRECTORY = linux_raw_sys::general::O_DIRECTORY;
 
-        /// `O_DSYNC`.
+        /// `O_DSYNC`
         const DSYNC = linux_raw_sys::general::O_SYNC;
 
         /// `O_EXCL`
         const EXCL = linux_raw_sys::general::O_EXCL;
 
-        /// `O_FSYNC`.
+        /// `O_FSYNC`
         const FSYNC = linux_raw_sys::general::O_SYNC;
 
         /// `O_NOFOLLOW`
@@ -226,7 +226,7 @@ bitflags! {
         /// `O_NOCTTY`
         const NOCTTY = linux_raw_sys::general::O_NOCTTY;
 
-        /// `O_RSYNC`.
+        /// `O_RSYNC`
         const RSYNC = linux_raw_sys::general::O_SYNC;
 
         /// `O_SYNC`
@@ -252,7 +252,7 @@ bitflags! {
 
         /// `O_LARGEFILE`
         ///
-        /// Tustix and/or libc will automatically set this flag when
+        /// 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.
@@ -486,13 +486,13 @@ bitflags! {
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct SealFlags: u32 {
-        /// `F_SEAL_SEAL`.
+        /// `F_SEAL_SEAL`
         const SEAL = linux_raw_sys::general::F_SEAL_SEAL;
-        /// `F_SEAL_SHRINK`.
+        /// `F_SEAL_SHRINK`
         const SHRINK = linux_raw_sys::general::F_SEAL_SHRINK;
-        /// `F_SEAL_GROW`.
+        /// `F_SEAL_GROW`
         const GROW = linux_raw_sys::general::F_SEAL_GROW;
-        /// `F_SEAL_WRITE`.
+        /// `F_SEAL_WRITE`
         const WRITE = linux_raw_sys::general::F_SEAL_WRITE;
         /// `F_SEAL_FUTURE_WRITE` (since Linux 5.1)
         const FUTURE_WRITE = linux_raw_sys::general::F_SEAL_FUTURE_WRITE;

src/backend/linux_raw/io/errno.rs

@@ -349,7 +349,7 @@ impl Errno {
     pub const ILSEQ: Self = Self::from_errno(errno::EILSEQ);
     /// `EINPROGRESS`
     pub const INPROGRESS: Self = Self::from_errno(errno::EINPROGRESS);
-    /// `EINTR`.
+    /// `EINTR`
     ///
     /// For a convenient way to retry system calls that exit with `INTR`, use
     /// [`retry_on_intr`].

src/backend/linux_raw/io/syscalls.rs

@@ -38,7 +38,7 @@ pub(crate) unsafe fn pread(
     len: usize,
     pos: u64,
 ) -> io::Result<usize> {
-    // <https://github.com/torvalds/linux/blob/fcadab740480e0e0e9fa9bd272acd409884d431a/arch/arm64/kernel/sys32.c#L75>
+    // <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/kernel/sys32.c?h=v6.13#n70>
     #[cfg(all(
         target_pointer_width = "32",
         any(target_arch = "arm", target_arch = "mips", target_arch = "mips32r6"),
@@ -142,7 +142,7 @@ pub(crate) fn write(fd: BorrowedFd<'_>, buf: &[u8]) -> io::Result<usize> {
 pub(crate) fn pwrite(fd: BorrowedFd<'_>, buf: &[u8], pos: u64) -> io::Result<usize> {
     let (buf_addr, buf_len) = slice(buf);
 
-    // <https://github.com/torvalds/linux/blob/fcadab740480e0e0e9fa9bd272acd409884d431a/arch/arm64/kernel/sys32.c#L81-L83>
+    // <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/arm64/kernel/sys32.c?h=v6.13#n76>
     #[cfg(all(
         target_pointer_width = "32",
         any(target_arch = "arm", target_arch = "mips", target_arch = "mips32r6"),

src/backend/linux_raw/net/addr.rs

@@ -187,12 +187,13 @@ impl fmt::Debug for SocketAddrUnix {
     }
 }
 
-/// `struct sockaddr_storage`.
+/// `struct sockaddr_storage`
 ///
 /// This type is guaranteed to be large enough to hold any encoded socket
 /// address.
 #[repr(transparent)]
 #[derive(Copy, Clone)]
+#[doc(alias = "sockaddr_storage")]
 pub struct SocketAddrStorage(c::sockaddr_storage);
 
 // SAFETY: Bindgen adds a union with a raw pointer for alignment but it's never
@@ -205,7 +206,7 @@ unsafe impl Sync for SocketAddrStorage {}
 
 impl SocketAddrStorage {
     /// Return a socket addr storage initialized to all zero bytes. The
-    /// `sa_family` is set to `AddressFamily::UNSPEC`.
+    /// `sa_family` is set to [`AddressFamily::UNSPEC`].
     pub fn zeroed() -> Self {
         assert_eq!(c::AF_UNSPEC, 0);
         // SAFETY: `sockaddr_storage` is meant to be zero-initializable.
@@ -223,7 +224,7 @@ impl SocketAddrStorage {
     }
 
     /// Clear the `sa_family` of this socket address to
-    /// `AddressFamily::UNSPEC`.
+    /// [`AddressFamily::UNSPEC`].
     pub fn clear_family(&mut self) {
         // SAFETY: `self.0` is a `sockaddr_storage` so it has enough space.
         unsafe {

src/backend/linux_raw/vdso.rs

@@ -1,7 +1,7 @@
 //! Parse the Linux vDSO.
 //!
 //! The following code is transliterated from
-//! tools/testing/selftests/vDSO/parse_vdso.c in Linux 6.12, which is licensed
+//! tools/testing/selftests/vDSO/parse_vdso.c in Linux 6.13, which is licensed
 //! with Creative Commons Zero License, version 1.0,
 //! available at <https://creativecommons.org/publicdomain/zero/1.0/legalcode>
 //!

src/event/select.rs

@@ -180,8 +180,7 @@ pub fn fd_set_remove(fds: &mut [FdSetElement], fd: RawFd) {
     }
 }
 
-/// Compute the minimum `nfds` value needed for the set pointed to by
-/// `fds`.
+/// Compute the minimum `nfds` value needed for the set pointed to by `fds`.
 #[inline]
 pub fn fd_set_bound(fds: &[FdSetElement]) -> RawFd {
     #[cfg(not(any(windows, target_os = "wasi")))]

src/fs/fd.rs

@@ -246,7 +246,7 @@ pub fn futimens<Fd: AsFd>(fd: Fd, times: &Timestamps) -> io::Result<()> {
     target_os = "nto",
     target_os = "redox",
     target_os = "vita",
-)))] // not implemented in libc for netbsd yet
+)))] // not implemented in libc for NetBSD yet
 #[inline]
 #[doc(alias = "posix_fallocate")]
 pub fn fallocate<Fd: AsFd>(fd: Fd, mode: FallocateFlags, offset: u64, len: u64) -> io::Result<()> {

src/io_uring/mod.rs

@@ -18,9 +18,9 @@
 //!  - [Linux]
 //!  - [io_uring header]
 //!
-//! [Linux]: https://man.archlinux.org/man/io_uring.7.en
+//! [Linux]: https://www.man7.org/linux/man-pages/man7/io_uring.7.html
 //! [io_uring]: https://en.wikipedia.org/wiki/Io_uring
-//! [io_uring header]: https://github.com/torvalds/linux/blob/master/include/uapi/linux/io_uring.h
+//! [io_uring header]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/io_uring.h?h=v6.13
 //! [rustix-uring]: https://crates.io/crates/rustix-uring
 #![allow(unsafe_code)]
 
@@ -68,7 +68,7 @@ mod sys {
 /// # References
 ///  - [Linux]
 ///
-/// [Linux]: https://man.archlinux.org/man/io_uring_setup.2.en
+/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_setup.2.html
 #[inline]
 pub fn io_uring_setup(entries: u32, params: &mut io_uring_params) -> io::Result<OwnedFd> {
     backend::io_uring::syscalls::io_uring_setup(entries, params)
@@ -88,7 +88,7 @@ pub fn io_uring_setup(entries: u32, params: &mut io_uring_params) -> io::Result<
 /// # References
 ///  - [Linux]
 ///
-/// [Linux]: https://man.archlinux.org/man/io_uring_register.2.en
+/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_register.2.html
 #[inline]
 pub unsafe fn io_uring_register<Fd: AsFd>(
     fd: Fd,
@@ -111,7 +111,7 @@ pub unsafe fn io_uring_register<Fd: AsFd>(
 /// # References
 ///  - [Linux]
 ///
-/// [Linux]: https://man.archlinux.org/man/io_uring_register.2.en
+/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_register.2.html
 #[inline]
 pub unsafe fn io_uring_register_with<Fd: AsFd>(
     fd: Fd,
@@ -135,7 +135,7 @@ pub unsafe fn io_uring_register_with<Fd: AsFd>(
 /// # References
 ///  - [Linux]
 ///
-/// [Linux]: https://man.archlinux.org/man/io_uring_enter.2.en
+/// [Linux]: https://www.man7.org/linux/man-pages/man2/io_uring_enter.2.html
 #[inline]
 pub unsafe fn io_uring_enter<Fd: AsFd>(
     fd: Fd,

src/lib.rs

@@ -402,4 +402,5 @@ mod timespec;
 mod ugid;
 
 #[cfg(doc)]
+#[cfg_attr(docsrs, doc(cfg(doc)))]
 pub mod not_implemented;

src/maybe_polyfill/no_std/os/fd/owned.rs

@@ -27,9 +27,14 @@ use core::mem::forget;
 /// passed as an argument, it is not captured or consumed, and it never has the
 /// value `-1`.
 ///
-/// This type's `.to_owned()` implementation returns another `BorrowedFd`
-/// rather than an `OwnedFd`. It just makes a trivial copy of the raw file
-/// descriptor, which is then borrowed under the same lifetime.
+/// This type does not have a [`ToOwned`][crate::borrow::ToOwned]
+/// implementation. Calling `.to_owned()` on a variable of this type will call
+/// it on `&BorrowedFd` and use `Clone::clone()` like `ToOwned` does for all
+/// types implementing `Clone`. The result will be descriptor borrowed under
+/// the same lifetime.
+///
+/// To obtain an [`OwnedFd`], you can use [`BorrowedFd::try_clone_to_owned`]
+/// instead, but this is not supported on all platforms.
 #[derive(Copy, Clone)]
 #[repr(transparent)]
 #[cfg_attr(rustc_attrs, rustc_layout_scalar_valid_range_start(0))]
@@ -53,6 +58,8 @@ pub struct BorrowedFd<'fd> {
 /// descriptor, so it can be used in FFI in places where a file descriptor is
 /// passed as a consumed argument or returned as an owned value, and it never
 /// has the value `-1`.
+///
+/// You can use [`AsFd::as_fd`] to obtain a [`BorrowedFd`].
 #[repr(transparent)]
 #[cfg_attr(rustc_attrs, rustc_layout_scalar_valid_range_start(0))]
 // libstd/os/raw/mod.rs assures me that every libstd-supported platform has a
@@ -66,7 +73,7 @@ pub struct OwnedFd {
 }
 
 impl BorrowedFd<'_> {
-    /// Return a `BorrowedFd` holding the given raw file descriptor.
+    /// Returns a `BorrowedFd` holding the given raw file descriptor.
     ///
     /// # Safety
     ///

src/maybe_polyfill/no_std/os/windows/io/raw.rs

@@ -45,10 +45,11 @@ pub trait FromRawSocket {
     /// # Safety
     ///
     /// The `socket` passed in must:
-    ///   - be a valid an open socket,
+    ///   - be an [owned socket][io-safety]; in particular, it must be open.
     ///   - be a socket that may be freed via [`closesocket`].
     ///
     /// [`closesocket`]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket
+    /// [io-safety]: io#io-safety
     #[cfg_attr(staged_api, stable(feature = "from_raw_os", since = "1.1.0"))]
     unsafe fn from_raw_socket(sock: RawSocket) -> Self;
 }

src/maybe_polyfill/no_std/os/windows/io/socket.rs

@@ -70,7 +70,7 @@ pub struct OwnedSocket {
 }
 
 impl BorrowedSocket<'_> {
-    /// Return a `BorrowedSocket` holding the given raw socket.
+    /// Returns a `BorrowedSocket` holding the given raw socket.
     ///
     /// # Safety
     ///

src/maybe_polyfill/std/mod.rs

@@ -19,7 +19,7 @@ pub mod net {
 
 pub mod os {
     pub mod fd {
-        // Change  to use `std::os::fd` when MSRV becomes 1.66 or higher.
+        // Change to use `std::os::fd` when MSRV becomes Rust 1.66 or higher.
 
         #[cfg(target_os = "wasi")]
         pub use std::os::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};