Minor comment formatting cleanups. (#561)

Use shorter docs.rs URLs in comments, update to upstream Rust files that
include more comments, and other miscellaenous comment formatting fixes.

Author: sunfishcode

README.md

@@ -70,20 +70,20 @@ by default. The rest of the API is conditional with cargo feature flags:
 |            |
 | `use-libc` | Enable the libc backend.
 
-[`rustix::fs`]: https://docs.rs/rustix/latest/rustix/fs/index.html
-[`rustix::io_uring`]: https://docs.rs/rustix/latest/rustix/io_uring/index.html
-[`rustix::mm`]: https://docs.rs/rustix/latest/rustix/mm/index.html
-[`rustix::net`]: https://docs.rs/rustix/latest/rustix/net/index.html
-[`rustix::param`]: https://docs.rs/rustix/latest/rustix/param/index.html
-[`rustix::process`]: https://docs.rs/rustix/latest/rustix/process/index.html
-[`rustix::rand`]: https://docs.rs/rustix/latest/rustix/rand/index.html
-[`rustix::termios`]: https://docs.rs/rustix/latest/rustix/termios/index.html
-[`rustix::thread`]: https://docs.rs/rustix/latest/rustix/thread/index.html
-[`rustix::time`]: https://docs.rs/rustix/latest/rustix/time/index.html
-[`rustix::io`]: https://docs.rs/rustix/latest/rustix/io/index.html
-[`rustix::fd`]: https://docs.rs/rustix/latest/rustix/fd/index.html
-[`rustix::ffi`]: https://docs.rs/rustix/latest/rustix/ffi/index.html
-[`rustix::path`]: https://docs.rs/rustix/latest/rustix/path/index.html
+[`rustix::fs`]: https://docs.rs/rustix/*/rustix/fs/index.html
+[`rustix::io_uring`]: https://docs.rs/rustix/*/rustix/io_uring/index.html
+[`rustix::mm`]: https://docs.rs/rustix/*/rustix/mm/index.html
+[`rustix::net`]: https://docs.rs/rustix/*/rustix/net/index.html
+[`rustix::param`]: https://docs.rs/rustix/*/rustix/param/index.html
+[`rustix::process`]: https://docs.rs/rustix/*/rustix/process/index.html
+[`rustix::rand`]: https://docs.rs/rustix/*/rustix/rand/index.html
+[`rustix::termios`]: https://docs.rs/rustix/*/rustix/termios/index.html
+[`rustix::thread`]: https://docs.rs/rustix/*/rustix/thread/index.html
+[`rustix::time`]: https://docs.rs/rustix/*/rustix/time/index.html
+[`rustix::io`]: https://docs.rs/rustix/*/rustix/io/index.html
+[`rustix::fd`]: https://docs.rs/rustix/*/rustix/fd/index.html
+[`rustix::ffi`]: https://docs.rs/rustix/*/rustix/ffi/index.html
+[`rustix::path`]: https://docs.rs/rustix/*/rustix/path/index.html
 
 ## Similar crates
 
@@ -152,10 +152,10 @@ version of this crate.
 [`timerfd`]: https://crates.io/crates/timerfd
 [`io-streams`]: https://crates.io/crates/io-streams
 [`bitflags`]: https://crates.io/crates/bitflags
-[`Arg`]: https://docs.rs/rustix/latest/rustix/path/trait.Arg.html
+[`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html
 [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
 [I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
 [provenance]: https://github.com/rust-lang/rust/issues/95228
-[`OwnedFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/struct.OwnedFd.html
-[`AsFd`]: https://docs.rs/io-lifetimes/latest/io_lifetimes/trait.AsFd.html
-[`NOSYS`]: https://docs.rs/rustix/latest/rustix/io/struct.Errno.html#associatedconstant.NOSYS
+[`OwnedFd`]: https://docs.rs/io-lifetimes/*/io_lifetimes/struct.OwnedFd.html
+[`AsFd`]: https://docs.rs/io-lifetimes/*/io_lifetimes/trait.AsFd.html
+[`NOSYS`]: https://docs.rs/rustix/*/rustix/io/struct.Errno.html#associatedconstant.NOSYS

examples/dup2_to_replace_stdio.rs

@@ -38,7 +38,7 @@ fn main() {
     drop(reader);
     drop(writer);
 
-    // Now we can print to "stdout" in the usual way, and it'll go to our pipe.
+    // Now we can print to “stdout” in the usual way, and it'll go to our pipe.
     println!("hello, world!");
 
     // And we can read from stdin, and it'll read from our pipe. It's a little

src/backend/libc/fs/dir.rs

@@ -237,7 +237,7 @@ unsafe fn read_dirent(input: &libc_dirent) -> libc_dirent {
     pub d_pino: i64,
     pub d_reclen: ::c_ushort,
     pub d_name: [::c_char; 1024], // Max length is _POSIX_PATH_MAX
-                                  // */
+    */
 
     // On dragonfly and FreeBSD 12, `dirent` has some non-public padding fields
     // so we can't directly initialize it.

src/backend/libc/fs/inotify.rs

@@ -81,7 +81,7 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
     unsafe { ret_owned_fd(c::inotify_init1(flags.bits())) }
 }
 
-/// `inotify_add_watch(self, path, flags)`-Adds a watch to inotify
+/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify
 ///
 /// This registers or updates a watch for the filesystem path `path`
 /// and returns a watch descriptor corresponding to this watch.
@@ -96,7 +96,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     flags: WatchFlags,
 ) -> io::Result<i32> {
     let path = path.as_cow_c_str().unwrap();
-    // SAFETY: The fd and path we are passing is guranteed valid by the type
+    // SAFETY: The fd and path we are passing is guaranteed valid by the type
     // system.
     unsafe {
         ret_c_int(c::inotify_add_watch(
@@ -107,7 +107,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     }
 }
 
-/// `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/libc/fs/syscalls.rs

@@ -162,7 +162,7 @@ pub(crate) fn openat(
     mode: Mode,
 ) -> io::Result<OwnedFd> {
     // Work around <https://sourceware.org/bugzilla/show_bug.cgi?id=17523>.
-    // Basically old glibc versions don't handle O_TMPFILE correctly.
+    // GLIBC versions before 2.25 don't handle `O_TMPFILE` correctly.
     #[cfg(all(unix, target_env = "gnu"))]
     if oflags.contains(OFlags::TMPFILE) && crate::backend::if_glibc_is_less_than_2_25() {
         return openat_via_syscall(dirfd, path, oflags, mode);
@@ -1593,7 +1593,7 @@ pub(crate) unsafe fn copyfile_state_get(
 
 #[cfg(apple)]
 pub(crate) fn getpath(fd: BorrowedFd<'_>) -> io::Result<CString> {
-    // The use of PATH_MAX is generally not encouraged, but it
+    // The use of `PATH_MAX` is generally not encouraged, but it
     // is inevitable in this case because macOS defines `fcntl` with
     // `F_GETPATH` in terms of `MAXPATHLEN`, and there are no
     // alternatives. If a better method is invented, it should be used

src/backend/libc/io/syscalls.rs

@@ -242,7 +242,7 @@ pub(crate) fn pwritev2(
 }
 
 // These functions are derived from Rust's library/std/src/sys/unix/fd.rs at
-// revision a77da2d454e6caa227a85b16410b95f93495e7e0.
+// revision 326ef470a8b379a180d6dc4bbef08990698a737a.
 
 // The maximum read limit on most POSIX-like systems is `SSIZE_MAX`, with the
 // man page quoting that if the count of bytes to read is greater than
@@ -262,7 +262,12 @@ const fn max_iov() -> usize {
     c::IOV_MAX as usize
 }
 
-#[cfg(any(target_os = "android", target_os = "emscripten", target_os = "linux"))]
+#[cfg(any(
+    target_os = "android",
+    target_os = "emscripten",
+    target_os = "linux",
+    target_os = "nto"
+))]
 const fn max_iov() -> usize {
     c::UIO_MAXIOV as usize
 }
@@ -272,6 +277,8 @@ const fn max_iov() -> usize {
     target_os = "android",
     target_os = "emscripten",
     target_os = "linux",
+    target_os = "nto",
+    target_os = "horizon",
 )))]
 const fn max_iov() -> usize {
     16 // The minimum value required by POSIX.

src/backend/linux_raw/fs/inotify.rs

@@ -80,7 +80,7 @@ pub fn inotify_init(flags: CreateFlags) -> io::Result<OwnedFd> {
     syscalls::inotify_init1(flags)
 }
 
-/// `inotify_add_watch(self, path, flags)`-Adds a watch to inotify
+/// `inotify_add_watch(self, path, flags)`—Adds a watch to inotify
 ///
 /// This registers or updates a watch for the filesystem path `path`
 /// and returns a watch descriptor corresponding to this watch.
@@ -98,7 +98,7 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
     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/io/kqueue.rs

@@ -310,7 +310,7 @@ impl UserDefinedFlags {
     }
 }
 
-/// `kqueue()`- Create a new `kqueue` file descriptor.
+/// `kqueue()`—Create a new `kqueue` file descriptor.
 ///
 /// # References
 ///
@@ -329,7 +329,8 @@ pub fn kqueue() -> io::Result<OwnedFd> {
     syscalls::kqueue()
 }
 
-/// `kevent()`- Wait for events on a `kqueue`.
+/// `kevent(kqueue, changelist, eventlist, timeout)`—Wait for events on a
+/// `kqueue`.
 ///
 /// # Safety
 ///

src/io/port.rs

@@ -1,4 +1,4 @@
-//! Solaris/Illumos event ports.
+//! Solaris/illumos event ports.
 
 use crate::backend::c;
 use crate::backend::io::syscalls;
@@ -31,7 +31,7 @@ impl Event {
     }
 }
 
-/// `port_create()`- Creates a new port.
+/// `port_create()`—Creates a new port.
 ///
 /// # References
 ///
@@ -44,7 +44,7 @@ pub fn port_create() -> io::Result<OwnedFd> {
     syscalls::port_create()
 }
 
-/// `port_associate(_, PORT_SOURCE_FD, _, _, _)`- Associates a file descriptor
+/// `port_associate(_, PORT_SOURCE_FD, _, _, _)`—Associates a file descriptor
 /// with a port.
 ///
 /// # Safety
@@ -75,7 +75,7 @@ pub unsafe fn port_associate_fd(
     )
 }
 
-/// `port_dissociate(_, PORT_SOURCE_FD, _)`- Dissociates a file descriptor from
+/// `port_dissociate(_, PORT_SOURCE_FD, _)`—Dissociates a file descriptor from
 /// a port.
 ///
 /// # Safety
@@ -94,7 +94,7 @@ pub unsafe fn port_dissociate_fd(port: impl AsFd, object: impl AsRawFd) -> io::R
     syscalls::port_dissociate(port.as_fd(), c::PORT_SOURCE_FD, object.as_raw_fd() as _)
 }
 
-/// `port_get(port, timeout)`- Gets an event from a port.
+/// `port_get(port, timeout)`—Gets an event from a port.
 ///
 /// # References
 ///
@@ -112,7 +112,7 @@ pub fn port_get(port: impl AsFd, timeout: Option<Duration>) -> io::Result<Event>
     syscalls::port_get(port.as_fd(), timeout.as_mut())
 }
 
-/// `port_getn(port, events, min_events, timeout)`- Gets multiple events from a
+/// `port_getn(port, events, min_events, timeout)`—Gets multiple events from a
 /// port.
 ///
 /// # References
@@ -143,7 +143,7 @@ pub fn port_getn(
     )
 }
 
-/// `port_send(port, events, userdata)`- Sends an event to a port.
+/// `port_send(port, events, userdata)`—Sends an event to a port.
 ///
 /// # References
 ///

src/lib.rs

@@ -90,7 +90,7 @@
 //! [`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html
 //! [I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md
 //! [`Result`]: https://doc.rust-lang.org/stable/std/result/enum.Result.html
-//! [`Arg`]: https://docs.rs/rustix/latest/rustix/path/trait.Arg.html
+//! [`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html
 
 #![deny(missing_docs)]
 #![allow(stable_features)]

src/net/addr.rs

@@ -1,6 +1,6 @@
 //! The following is derived from Rust's
 //! library/std/src/net/socket_addr.rs at revision
-//! f7e8ba28a4785e698a55fb95e4b3e803302de0ff.
+//! bd20fc1fd657b32f7aa1d70d8723f04c87f21606.
 //!
 //! All code in this file is licensed MIT or Apache 2.0 at your option.
 //!

src/net/ip.rs

@@ -1,6 +1,6 @@
 //! The following is derived from Rust's
 //! library/std/src/net/ip_addr.rs at revision
-//! 14230a7f8e117aa049d3ae661fa00ded7edefc68.
+//! bd20fc1fd657b32f7aa1d70d8723f04c87f21606.
 //!
 //! All code in this file is licensed MIT or Apache 2.0 at your option.
 //!
@@ -1223,6 +1223,9 @@ impl Ipv6Addr {
 
     /// An IPv6 address representing localhost: `::1`.
     ///
+    /// This corresponds to constant `IN6ADDR_LOOPBACK_INIT` or `in6addr_loopback` in other
+    /// languages.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1231,11 +1234,15 @@ impl Ipv6Addr {
     /// let addr = Ipv6Addr::LOCALHOST;
     /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
     /// ```
+    #[doc(alias = "IN6ADDR_LOOPBACK_INIT")]
+    #[doc(alias = "in6addr_loopback")]
     #[cfg_attr(staged_api, stable(feature = "ip_constructors", since = "1.30.0"))]
     pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
 
     /// An IPv6 address representing the unspecified address: `::`
     ///
+    /// This corresponds to constant `IN6ADDR_ANY_INIT` or `in6addr_any` in other languages.
+    ///
     /// # Examples
     ///
     /// ```
@@ -1244,6 +1251,8 @@ impl Ipv6Addr {
     /// let addr = Ipv6Addr::UNSPECIFIED;
     /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0));
     /// ```
+    #[doc(alias = "IN6ADDR_ANY_INIT")]
+    #[doc(alias = "in6addr_any")]
     #[cfg_attr(staged_api, stable(feature = "ip_constructors", since = "1.30.0"))]
     pub const UNSPECIFIED: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0);
 

src/net/mod.rs

@@ -4,8 +4,8 @@
 //! of these APIs. [`wsa_cleanup`] may be used in the process if these APIs are
 //! no longer needed.
 //!
-//! [`wsa_startup`]: https://docs.rs/rustix/latest/x86_64-pc-windows-msvc/rustix/net/fn.wsa_startup.html
-//! [`wsa_cleanup`]: https://docs.rs/rustix/latest/x86_64-pc-windows-msvc/rustix/net/fn.wsa_cleanup.html
+//! [`wsa_startup`]: https://docs.rs/rustix/*/x86_64-pc-windows-msvc/rustix/net/fn.wsa_startup.html
+//! [`wsa_cleanup`]: https://docs.rs/rustix/*/x86_64-pc-windows-msvc/rustix/net/fn.wsa_cleanup.html
 
 #[cfg(not(feature = "std"))]
 mod addr;

src/path/arg.rs

@@ -950,7 +950,7 @@ where
     }
 
     // Taken from
-    // https://github.com/rust-lang/rust/blob/a00f8ba7fcac1b27341679c51bf5a3271fa82df3/library/std/src/sys/common/small_c_string.rs
+    // <https://github.com/rust-lang/rust/blob/a00f8ba7fcac1b27341679c51bf5a3271fa82df3/library/std/src/sys/common/small_c_string.rs>
     let mut buf = MaybeUninit::<[u8; SMALL_PATH_BUFFER_SIZE]>::uninit();
     let buf_ptr = buf.as_mut_ptr() as *mut u8;
 

src/process/rlimit.rs

@@ -8,9 +8,9 @@ pub use backend::process::types::Resource;
 /// [`setrlimit`], and [`prlimit`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Rlimit {
-    /// Current effective, "soft", limit.
+    /// Current effective, “soft”, limit.
     pub current: Option<u64>,
-    /// Maximum, "hard", value that `current` may be dynamically increased to.
+    /// Maximum, “hard”, value that `current` may be dynamically increased to.
     pub maximum: Option<u64>,
 }
 

src/process/wait.rs

@@ -175,7 +175,7 @@ pub fn wait(waitopts: WaitOptions) -> io::Result<Option<(Pid, WaitStatus)>> {
     backend::process::syscalls::wait(waitopts)
 }
 
-/// `waitid(_, _, _, opts)`-Wait for the specified child process to change
+/// `waitid(_, _, _, opts)`—Wait for the specified child process to change
 /// state.
 #[cfg(not(any(target_os = "wasi", target_os = "redox", target_os = "openbsd")))]
 #[inline]

tests/fs/invalid_offset.rs

@@ -4,7 +4,7 @@
 //! Rust APIs tend to use `u64`. Test that extreme `u64` values in APIs that
 //! take file offsets are properly diagnosed.
 //!
-//! These tests are disabled on ios/macos since those platforms kill the
+//! These tests are disabled on iOS/macOS since those platforms kill the
 //! process with `SIGXFSZ` instead of returning an error.
 
 #![cfg(not(any(target_os = "redox", target_os = "wasi")))]

tests/io/main.rs

@@ -25,7 +25,7 @@ mod poll;
 mod procfs;
 #[cfg(not(windows))]
 #[cfg(not(target_os = "redox"))] // redox doesn't have cwd/openat
-#[cfg(not(target_os = "wasi"))] // wasi support for S_IRUSR etc. submitted to libc in #2264
+#[cfg(not(target_os = "wasi"))] // wasi support for `S_IRUSR` etc. submitted to libc in #2264
 mod read_write;
 #[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "android"))]
 mod seals;

tests/process/prctl.rs

@@ -115,9 +115,9 @@ fn test_floating_point_emulation_control() {
     dbg!(floating_point_emulation_control().unwrap());
 }
 
-/*
- * Helper functions.
- */
+//
+// Helper functions.
+//
 
 #[cfg(feature = "thread")]
 pub(crate) fn thread_has_capability(capability: Capability) -> io::Result<bool> {

tests/process/working_directory.rs

@@ -7,7 +7,7 @@ fn tmpdir() -> TempDir {
     tempdir().expect("expected to be able to create a temporary directory")
 }
 
-/// Disable this test on macos because GHA has a weird system folder structure
+/// Disable this test on macOS because GHA has a weird system folder structure
 /// that makes this test fail.
 #[cfg(not(target_os = "macos"))]
 #[test]

tests/thread/prctl.rs

@@ -105,9 +105,9 @@ fn test_core_scheduling_cookie() {
     }
 }
 
-/*
- * Helper functions.
- */
+//
+// Helper functions.
+//
 
 fn load_linux_kernel_config() -> io::Result<Vec<u8>> {
     if let Ok(compressed_bytes) = fs::read("/proc/config.gz") {