Misc documentation cleanups. (#1120)

Author: sunfishcode

src/backend/libc/fs/syscalls.rs

@@ -2255,8 +2255,8 @@ pub(crate) fn getxattr(path: &CStr, name: &CStr, value: &mut [u8]) -> io::Result
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass null
-        // instead.
+        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
+        // null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {
@@ -2291,8 +2291,8 @@ pub(crate) fn lgetxattr(path: &CStr, name: &CStr, value: &mut [u8]) -> io::Resul
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass null
-        // instead.
+        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
+        // null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {
@@ -2328,8 +2328,8 @@ pub(crate) fn fgetxattr(fd: BorrowedFd<'_>, name: &CStr, value: &mut [u8]) -> io
 
     #[cfg(apple)]
     {
-        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass null
-        // instead.
+        // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass
+        // null instead.
         let ptr = if value.is_empty() {
             core::ptr::null_mut()
         } else {

src/backend/libc/pipe/types.rs

@@ -37,6 +37,10 @@ bitflags! {
 bitflags! {
     /// `SPLICE_F_*` constants for use with [`splice`], [`vmsplice`], and
     /// [`tee`].
+    ///
+    /// [`splice`]: crate::pipe::splice
+    /// [`vmsplice`]: crate::pipe::splice
+    /// [`tee`]: crate::pipe::tee
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct SpliceFlags: c::c_uint {

src/backend/libc/process/syscalls.rs

@@ -380,7 +380,7 @@ pub(crate) fn prlimit(pid: Option<Pid>, limit: Resource, new: Rlimit) -> io::Res
     }
 }
 
-/// Convert a Rust [`Rlimit`] to a C `c::rlimit`.
+/// Convert a C `c::rlimit` to a Rust `Rlimit`.
 #[cfg(not(any(
     target_os = "espidf",
     target_os = "fuchsia",
@@ -402,7 +402,7 @@ fn rlimit_from_libc(lim: c::rlimit) -> Rlimit {
     Rlimit { current, maximum }
 }
 
-/// Convert a C `c::rlimit` to a Rust `Rlimit`.
+/// Convert a Rust [`Rlimit`] to a C `c::rlimit`.
 #[cfg(not(any(
     target_os = "espidf",
     target_os = "fuchsia",

src/backend/linux_raw/param/auxv.rs

@@ -145,7 +145,7 @@ pub(in super::super) fn sysinfo_ehdr() -> *const Elf_Ehdr {
     let mut ehdr = SYSINFO_EHDR.load(Relaxed);
 
     if ehdr.is_null() {
-        // Use `maybe_init_auxv` to to read the aux vectors if it can, but do
+        // Use `maybe_init_auxv` to read the aux vectors if it can, but do
         // nothing if it can't. If it can't, then we'll get a null pointer
         // here, which our callers are prepared to deal with.
         maybe_init_auxv();

src/backend/linux_raw/pipe/types.rs

@@ -24,6 +24,10 @@ bitflags! {
 bitflags! {
     /// `SPLICE_F_*` constants for use with [`splice`], [`vmsplice`], and
     /// [`tee`].
+    ///
+    /// [`splice`]: crate::pipe::splice
+    /// [`vmsplice`]: crate::pipe::splice
+    /// [`tee`]: crate::pipe::tee
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct SpliceFlags: c::c_uint {

src/backend/linux_raw/process/syscalls.rs

@@ -345,7 +345,7 @@ pub(crate) fn prlimit(pid: Option<Pid>, limit: Resource, new: Rlimit) -> io::Res
     }
 }
 
-/// Convert a Rust [`Rlimit`] to a C `rlimit64`.
+/// Convert a C `rlimit64` to a Rust `Rlimit`.
 #[inline]
 fn rlimit_from_linux(lim: rlimit64) -> Rlimit {
     let current = if lim.rlim_cur == RLIM64_INFINITY as _ {
@@ -361,7 +361,7 @@ fn rlimit_from_linux(lim: rlimit64) -> Rlimit {
     Rlimit { current, maximum }
 }
 
-/// Convert a C `rlimit64` to a Rust `Rlimit`.
+/// Convert a Rust [`Rlimit`] to a C `rlimit64`.
 #[inline]
 fn rlimit_to_linux(lim: Rlimit) -> rlimit64 {
     let rlim_cur = match lim.current {

src/fs/mod.rs

@@ -7,7 +7,8 @@ mod constants;
 #[cfg(linux_kernel)]
 mod copy_file_range;
 #[cfg(not(any(target_os = "espidf", target_os = "redox")))]
-#[cfg(not(target_os = "haiku"))] // Haiku needs <https://github.com/rust-lang/rust/pull/112371>
+#[cfg(not(target_os = "haiku"))]
+// Haiku needs <https://git.haiku-os.org/haiku/commit/?id=b8caef69155fbe87def579305622b9718d7779dc>
 mod cwd;
 #[cfg(all(feature = "alloc", not(any(target_os = "espidf", target_os = "redox"))))]
 mod dir;
@@ -75,7 +76,8 @@ pub use constants::*;
 #[cfg(linux_kernel)]
 pub use copy_file_range::copy_file_range;
 #[cfg(not(any(target_os = "espidf", target_os = "redox")))]
-#[cfg(not(target_os = "haiku"))] // Haiku needs <https://github.com/rust-lang/rust/pull/112371>
+#[cfg(not(target_os = "haiku"))]
+// Haiku needs <https://git.haiku-os.org/haiku/commit/?id=b8caef69155fbe87def579305622b9718d7779dc>
 pub use cwd::*;
 #[cfg(all(feature = "alloc", not(any(target_os = "espidf", target_os = "redox"))))]
 pub use dir::{Dir, DirEntry};

src/process/sched.rs

@@ -151,7 +151,7 @@ pub fn sched_getaffinity(pid: Option<Pid>) -> io::Result<CpuSet> {
 ///  - [Linux]
 ///  - [DragonFly BSD]
 ///
-/// [Linux]: https://man7.org/linux/man-pages/man2/sched_getcpu.2.html
+/// [Linux]: https://man7.org/linux/man-pages/man3/sched_getcpu.3.html
 /// [DragonFly BSD]: https://man.dragonflybsd.org/?command=sched_getcpu&section=2
 // FreeBSD added `sched_getcpu` in 13.0.
 #[cfg(any(linux_kernel, target_os = "dragonfly"))]

src/runtime.rs

@@ -408,8 +408,8 @@ pub unsafe fn sigaltstack(new: Option<Stack>) -> io::Result<Stack> {
 /// # Safety
 ///
 /// You're on your own. And on top of all the troubles with signal handlers,
-/// this implementation is highly experimental. The warning about the hazard
-/// of recycled thread ID's applies.
+/// this implementation is highly experimental. Also, this is not `tgkill`, so
+/// the warning about the hazard of recycled thread ID's applies.
 ///
 /// # References
 ///  - [Linux]
@@ -420,7 +420,7 @@ pub unsafe fn tkill(tid: Pid, sig: Signal) -> io::Result<()> {
     backend::runtime::syscalls::tkill(tid, sig)
 }
 
-/// `sigprocmask(how, set, oldset)`—Adjust the process signal mask.
+/// `rt_sigprocmask(how, set, oldset)`—Adjust the process signal mask.
 ///
 /// # Safety
 ///
@@ -429,10 +429,10 @@ pub unsafe fn tkill(tid: Pid, sig: Signal) -> io::Result<()> {
 /// the libc `sigprocmask` in several non-obvious and unsafe ways.
 ///
 /// # References
-///  - [Linux `sigprocmask`]
+///  - [Linux `rt_sigprocmask`]
 ///  - [Linux `pthread_sigmask`]
 ///
-/// [Linux `sigprocmask`]: https://man7.org/linux/man-pages/man2/sigprocmask.2.html
+/// [Linux `rt_sigprocmask`]: https://man7.org/linux/man-pages/man2/rt_sigprocmask.2.html
 /// [Linux `pthread_sigmask`]: https://man7.org/linux/man-pages/man3/pthread_sigmask.3.html
 #[inline]
 #[doc(alias = "pthread_sigmask")]

src/termios/tc.rs

@@ -82,7 +82,7 @@ pub fn tcsetpgrp<Fd: AsFd>(fd: Fd, pid: Pid) -> io::Result<()> {
 
 /// `tcsetattr(fd)`—Set terminal attributes.
 ///
-/// Also known as the `TCSETS` (or `TCSETS2 on Linux) operation with `ioctl`.
+/// Also known as the `TCSETS` (or `TCSETS2` on Linux) operation with `ioctl`.
 ///
 /// # References
 ///  - [POSIX `tcsetattr`]