Miscellaneous documentation cleanups. (#894)

bytecodealliance · Oct 24, 2023 · 0b7ccf4 · 0b7ccf4
1 parent 3f338d8
commit 0b7ccf4
Show file tree

Hide file tree

Showing 68 changed files with 289 additions and 282 deletions.
diff --git a/README.md b/README.md
@@ -55,28 +55,28 @@ building.
 The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled
 by default. The rest of the API is conditional with cargo feature flags:
 
-| Name       | Description
-| ---------- | ---------------------
-| `event`    | [`rustix::event`]—Polling and event operations.
-| `fs`       | [`rustix::fs`]—Filesystem operations.
-| `io_uring` | [`rustix::io_uring`]—Linux io_uring.
-| `mm`       | [`rustix::mm`]—Memory map operations.
-| `mount`    | [`rustix::mount`]—Linux mount API.
-| `net`      | [`rustix::net`]—Network-related operations.
-| `param`    | [`rustix::param`]—Process parameters.
-| `pipe`     | [`rustix::pipe`]—Pipe operations.
-| `process`  | [`rustix::process`]—Process-associated operations.
-| `procfs`   | [`rustix::procfs`]—Utilities for reading `/proc` on Linux.
-| `pty`      | [`rustix::pty`]—Pseudoterminal operations.
-| `rand`     | [`rustix::rand`]—Random-related operations.
-| `shm`      | [`rustix::shm`]—POSIX shared memory.
-| `stdio`    | [`rustix::stdio`]—Stdio-related operations.
-| `system`   | [`rustix::system`]—System-related operations.
-| `termios`  | [`rustix::termios`]—Terminal I/O stream operations.
-| `thread`   | [`rustix::thread`]—Thread-associated operations.
-| `time`     | [`rustix::time`]—Time-related operations.
-|            |
-| `use-libc` | Enable the libc backend.
+| Name       | Description                                                    |
+| ---------- | -------------------------------------------------------------- |
+| `event`    | [`rustix::event`]—Polling and event operations.                |
+| `fs`       | [`rustix::fs`]—Filesystem operations.                          |
+| `io_uring` | [`rustix::io_uring`]—Linux io_uring.                           |
+| `mm`       | [`rustix::mm`]—Memory map operations.                          |
+| `mount`    | [`rustix::mount`]—Linux mount API.                             |
+| `net`      | [`rustix::net`]—Network-related operations.                    |
+| `param`    | [`rustix::param`]—Process parameters.                          |
+| `pipe`     | [`rustix::pipe`]—Pipe operations.                              |
+| `process`  | [`rustix::process`]—Process-associated operations.             |
+| `procfs`   | [`rustix::procfs`]—Utilities for reading `/proc` on Linux.     |
+| `pty`      | [`rustix::pty`]—Pseudoterminal operations.                     |
+| `rand`     | [`rustix::rand`]—Random-related operations.                    |
+| `shm`      | [`rustix::shm`]—POSIX shared memory.                           |
+| `stdio`    | [`rustix::stdio`]—Stdio-related operations.                    |
+| `system`   | [`rustix::system`]—System-related operations.                  |
+| `termios`  | [`rustix::termios`]—Terminal I/O stream operations.            |
+| `thread`   | [`rustix::thread`]—Thread-associated operations.               |
+| `time`     | [`rustix::time`]—Time-related operations.                      |
+|            |                                                                |
+| `use-libc` | Enable the libc backend.                                       |
 
 [`rustix::event`]: https://docs.rs/rustix/*/rustix/event/index.html
 [`rustix::fs`]: https://docs.rs/rustix/*/rustix/fs/index.html

diff --git a/examples/termios.rs b/examples/termios.rs
@@ -28,7 +28,7 @@ fn main() -> std::io::Result<()> {
 
     tcsetattr(&tty, OptionalActions::Flush, &raw)?;
 
-    print!("Raw settings; press any key...");
+    print!("Raw settings; press any key…");
     std::io::stdout().flush()?;
     let mut buf = [0_u8];
     let _input = std::io::stdin().read(&mut buf)?;

diff --git a/src/backend/libc/event/epoll.rs b/src/backend/libc/event/epoll.rs
@@ -1,8 +1,4 @@
-//! epoll support.
-//!
-//! This is an experiment, and it isn't yet clear whether epoll is the right
-//! level of abstraction at which to introduce safety. But it works fairly well
-//! in simple examples 🙂.
+//! Linux `epoll` support.
 //!
 //! # Examples
 //!
@@ -96,7 +92,7 @@ bitflags! {
         /// `EPOLL_CLOEXEC`
         const CLOEXEC = bitcast!(c::EPOLL_CLOEXEC);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -152,7 +148,7 @@ bitflags! {
         #[cfg(not(target_os = "android"))]
         const EXCLUSIVE = bitcast!(c::EPOLLEXCLUSIVE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }

diff --git a/src/backend/libc/event/poll_fd.rs b/src/backend/libc/event/poll_fd.rs
@@ -48,7 +48,7 @@ bitflags! {
         )]
         const RDHUP = c::POLLRDHUP;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }

diff --git a/src/backend/libc/event/types.rs b/src/backend/libc/event/types.rs
@@ -31,7 +31,7 @@ bitflags! {
         #[cfg(not(target_os = "espidf"))]
         const SEMAPHORE = bitcast!(c::EFD_SEMAPHORE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
diff --git a/src/backend/libc/fs/inotify.rs b/src/backend/libc/fs/inotify.rs
@@ -18,7 +18,7 @@ bitflags! {
         /// `IN_NONBLOCK`
         const NONBLOCK = bitcast!(c::IN_NONBLOCK);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -75,7 +75,7 @@ bitflags! {
         /// `IN_ONLYDIR`
         const ONLYDIR = c::IN_ONLYDIR;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }

diff --git a/src/backend/libc/fs/types.rs b/src/backend/libc/fs/types.rs
@@ -21,7 +21,7 @@ bitflags! {
         /// `F_OK`
         const EXISTS = c::F_OK;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -77,7 +77,7 @@ bitflags! {
         #[cfg(all(target_os = "linux", target_env = "gnu"))]
         const STATX_DONT_SYNC = bitcast!(c::AT_STATX_DONT_SYNC);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -151,7 +151,7 @@ bitflags! {
         #[cfg(not(any(target_os = "espidf", target_os = "vita")))]
         const SVTX = c::S_ISVTX as RawMode;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -328,7 +328,7 @@ bitflags! {
         #[cfg(target_os = "freebsd")]
         const EMPTY_PATH = bitcast!(c::O_EMPTY_PATH);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -347,7 +347,7 @@ bitflags! {
         /// `CLONE_NOOWNERCOPY`
         const NOOWNERCOPY = 2;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -392,7 +392,7 @@ bitflags! {
         /// `COPYFILE_ALL`
         const ALL = copyfile::ALL;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -423,7 +423,7 @@ bitflags! {
         /// `RESOLVE_CACHED` (since Linux 5.12)
         const CACHED = 0x20;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -445,7 +445,7 @@ bitflags! {
         /// `RENAME_WHITEOUT`
         const WHITEOUT = bitcast!(c::RENAME_WHITEOUT);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -625,7 +625,7 @@ bitflags! {
         /// `MFD_HUGE_16GB`
         const HUGE_16GB = c::MFD_HUGE_16GB;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -652,7 +652,7 @@ bitflags! {
         #[cfg(linux_kernel)]
         const FUTURE_WRITE = bitcast!(c::F_SEAL_FUTURE_WRITE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -713,7 +713,7 @@ bitflags! {
         /// `STATX_ALL`
         const ALL = c::STATX_ALL;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -774,7 +774,7 @@ bitflags! {
         /// `STATX_ALL`
         const ALL = 0xfff;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -867,7 +867,7 @@ bitflags! {
         )))]
         const UNSHARE_RANGE = bitcast!(c::FALLOC_FL_UNSHARE_RANGE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -919,7 +919,7 @@ bitflags! {
         #[cfg(any(linux_kernel, target_os = "emscripten", target_os = "fuchsia"))]
         const SYNCHRONOUS = c::ST_SYNCHRONOUS as u64;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }

diff --git a/src/backend/libc/io/types.rs b/src/backend/libc/io/types.rs
@@ -12,7 +12,7 @@ bitflags! {
         /// `FD_CLOEXEC`
         const CLOEXEC = bitcast!(c::FD_CLOEXEC);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -37,7 +37,7 @@ bitflags! {
         /// `RWF_APPEND` (since Linux 4.16)
         const APPEND = linux_raw_sys::general::RWF_APPEND;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -59,7 +59,7 @@ bitflags! {
         )))] // Android 5.0 has dup3, but libc doesn't have bindings
         const CLOEXEC = bitcast!(c::O_CLOEXEC);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
diff --git a/src/backend/libc/mm/types.rs b/src/backend/libc/mm/types.rs
@@ -17,7 +17,7 @@ bitflags! {
         /// `PROT_EXEC`
         const EXEC = bitcast!(c::PROT_EXEC);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -59,7 +59,7 @@ bitflags! {
         #[cfg(all(linux_kernel, any(target_arch = "sparc", target_arch = "sparc64")))]
         const ADI = linux_raw_sys::general::PROT_ADI;
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -231,7 +231,7 @@ bitflags! {
         #[cfg(any())]
         const UNINITIALIZED = bitcast!(c::MAP_UNINITIALIZED);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -250,7 +250,7 @@ bitflags! {
         /// `MREMAP_MAYMOVE`
         const MAYMOVE = bitcast!(c::MREMAP_MAYMOVE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -272,7 +272,7 @@ bitflags! {
         /// written).
         const INVALIDATE = bitcast!(c::MS_INVALIDATE);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -288,7 +288,7 @@ bitflags! {
         /// `MLOCK_ONFAULT`
         const ONFAULT = bitcast!(c::MLOCK_ONFAULT);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -438,7 +438,7 @@ bitflags! {
         /// `O_NONBLOCK`
         const NONBLOCK = bitcast!(c::O_NONBLOCK);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }
@@ -462,7 +462,7 @@ bitflags! {
         /// the process.
         const CURRENT = bitcast!(libc::MCL_CURRENT);
 
-        /// <https://docs.rs/bitflags/latest/bitflags/#externally-defined-flags>
+        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
         const _ = !0;
     }
 }