Documentation and comment cleanups.

Author: sunfishcode

src/backend/libc/c.rs

@@ -12,7 +12,7 @@ pub(crate) const PROC_SUPER_MAGIC: u32 = 0x0000_9fa0;
 #[cfg(all(linux_kernel, target_env = "musl"))]
 pub(crate) const NFS_SUPER_MAGIC: u32 = 0x0000_6969;
 
-// Submitted upstream in https://github.com/rust-lang/libc/pull/3272.
+// Submitted upstream in <https://github.com/rust-lang/libc/pull/3272>.
 #[cfg(all(linux_kernel, feature = "net"))]
 pub(crate) const IPPROTO_ETHERNET: c_int = linux_raw_sys::net::IPPROTO_ETHERNET as _;
 

src/backend/libc/fs/types.rs

@@ -172,7 +172,7 @@ impl From<RawMode> for Mode {
 }
 
 impl From<Mode> for RawMode {
-    /// Support conversions from `Mode to raw mode values.
+    /// Support conversions from `Mode` to raw mode values.
     ///
     /// ```
     /// use rustix::fs::{Mode, RawMode};

src/backend/libc/net/read_sockaddr.rs

@@ -1,3 +1,6 @@
+//! The BSD sockets API requires us to read the `ss_family` field before
+//! we can interpret the rest of a `sockaddr` produced by the kernel.
+
 #[cfg(unix)]
 use super::addr::SocketAddrUnix;
 use super::ext::{in6_addr_s6_addr, in_addr_s_addr, sockaddr_in6_sin6_scope_id};
@@ -44,6 +47,11 @@ pub(crate) unsafe fn initialize_family_to_unspec(storage: *mut c::sockaddr_stora
     (*storage.cast::<sockaddr_header>()).ss_family = c::AF_UNSPEC as _;
 }
 
+/// Read a socket address encoded in a platform-specific format.
+///
+/// # Safety
+///
+/// `storage` must point to valid socket address storage.
 pub(crate) unsafe fn read_sockaddr(
     storage: *const c::sockaddr_storage,
     len: usize,

src/backend/linux_raw/param/libc_auxv.rs

@@ -15,7 +15,7 @@ use core::ptr::null;
 use core::slice;
 
 // `getauxval` wasn't supported in glibc until 2.16. Also this lets us use
-// `*mut` as the retrn type to preserve strict provenance.
+// `*mut` as the return type to preserve strict provenance.
 #[cfg(not(feature = "runtime"))]
 weak!(fn getauxval(c::c_ulong) -> *mut c::c_void);
 

src/check_types.rs

@@ -17,7 +17,7 @@ macro_rules! check_type {
 }
 
 /// The same as `check_type`, but for unions and anonymous structs we've
-/// renamed to avoid having types like "bindgen_ty_1" in the API.
+/// renamed to avoid having types like `bindgen_ty_1` in the API.
 macro_rules! check_renamed_type {
     ($to:ident, $from:ident) => {
         assert_eq!(
@@ -48,7 +48,7 @@ macro_rules! check_struct_field {
 }
 
 /// The same as `check_struct_field`, but for unions and anonymous structs
-/// we've renamed to avoid having types like "bindgen_ty_1" in the API.
+/// we've renamed to avoid having types like `bindgen_ty_1` in the API.
 macro_rules! check_struct_renamed_field {
     ($struct:ident, $to:ident, $from:ident) => {
         assert_eq!(

src/event/kqueue.rs

@@ -226,7 +226,7 @@ pub enum EventFilter {
 }
 
 bitflags::bitflags! {
-    /// The flags for a `kqueue` event.
+    /// The flags for a `kqueue` event specifying actions to perform.
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct EventFlags: u16 {
         /// Add the event to the `kqueue`.

src/fs/at.rs

@@ -99,20 +99,26 @@ fn _readlinkat(dirfd: BorrowedFd<'_>, path: &CStr, mut buffer: Vec<u8>) -> io::R
             }
 
             // SAFETY:
-            // - "readlink places the contents of the symbolic link pathname in the buffer buf"
-            // - POSIX definition 3.271 Pathname (https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_271
-            //   "A string that is used to identify a file."
-            //   POSIX definition 3.375: String (https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_375)
-            //   "A contiguous sequence of bytes terminated by and including the first null byte."
+            // - "readlink places the contents of the symbolic link pathname in the buffer
+            //   buf"
+            // - [POSIX definition 3.271: Pathname]: "A string that is used to identify a
+            //   file."
+            // - [POSIX definition 3.375: String]: "A contiguous sequence of bytes
+            //   terminated by and including the first null byte."
             // - "readlink does not append a terminating null byte to buf."
             //
             // Thus, there will be no NUL bytes in the string.
+            //
+            // [POSIX definition 3.271: Pathname]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_271
+            // [POSIX definition 3.375: String]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_375
             unsafe {
                 return Ok(CString::from_vec_unchecked(buffer));
             }
         }
 
-        buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation strategy to grow capacity exponentially
+        buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation
+                                               // strategy to grow capacity
+                                               // exponentially
     }
 }
 

src/fs/cwd.rs

@@ -25,13 +25,13 @@ use backend::fd::{BorrowedFd, RawFd};
 // SAFETY: `AT_FDCWD` is a reserved value that is never dynamically
 // allocated, so it'll remain valid for the duration of `'static`.
 #[doc(alias = "AT_FDCWD")]
-#[cfg(not(target_os = "haiku"))] // Haiku needs https://github.com/rust-lang/rust/pull/112371
+#[cfg(not(target_os = "haiku"))] // Haiku needs <https://github.com/rust-lang/rust/pull/112371>
 pub const CWD: BorrowedFd<'static> =
     unsafe { BorrowedFd::<'static>::borrow_raw(c::AT_FDCWD as RawFd) };
 
 /// Return the value of [`CWD`].
 #[deprecated(note = "Use `CWD` in place of `cwd()`.")]
-#[cfg(not(target_os = "haiku"))] // Haiku needs https://github.com/rust-lang/rust/pull/112371
+#[cfg(not(target_os = "haiku"))] // Haiku needs <https://github.com/rust-lang/rust/pull/112371>
 pub const fn cwd() -> BorrowedFd<'static> {
     let at_fdcwd = c::AT_FDCWD as RawFd;
 

src/lib.rs

@@ -120,8 +120,8 @@
 #![allow(clippy::unnecessary_cast)]
 // It is common in linux and libc APIs for types to vary between platforms.
 #![allow(clippy::useless_conversion)]
-// Redox and WASI have enough differences that it isn't worth
-// precisely conditionallizing all the `use`s for them.
+// Redox and WASI have enough differences that it isn't worth precisely
+// conditionalizing all the `use`s for them.
 #![cfg_attr(any(target_os = "redox", target_os = "wasi"), allow(unused_imports))]
 
 #[cfg(not(feature = "rustc-dep-of-std"))]

src/net/send_recv/mod.rs

@@ -1,4 +1,4 @@
-//! `recv` and `send`, and variants.
+//! `recv`, `send`, and variants.
 
 #[cfg(unix)]
 use crate::net::SocketAddrUnix;