Miscellaneous documentaion cleanups. (#1343)

- Update documentation links to Linux 6.13.
 - Use shorter forms of docs.rs links.
 - Fix typos in comments.
 - Update some maybe_polyfill comments to match upstream.
 - Comment formatting.
 - Update io_uring documentation links to point to man7.org.
 - Add some useful docs.
 - Tidying the not_implmented docs.
 - Fix a doc link in CHANGES.md.
 - Add doc aliases.

Author: sunfishcode

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`].