Improve comments and documentation. (#1332)

Author: sunfishcode

Cargo.toml

@@ -110,7 +110,7 @@ targets = [
 default = ["std", "use-libc-auxv"]
 
 # This enables use of std. Disabling this enables `#![no_std]`, and requires
-# Rust 1.64 or newer.
+# Rust 1.77 or newer.
 std = ["bitflags/std", "alloc", "libc?/std", "libc_errno?/std"]
 
 # Enable this to request the libc backend.
@@ -172,6 +172,9 @@ system = ["linux-raw-sys/system"]
 runtime = ["linux-raw-sys/prctl"]
 
 # Enable all API features.
+#
+# This is primarily intended for rustix developers. Users are encouraged to
+# enable only those features they need.
 all-apis = [
     "event",
     "fs",

src/backend/libc/fs/dir.rs

@@ -330,9 +330,9 @@ impl DirEntry {
         &self.name
     }
 
-    /// Returns the "offset" of this directory entry. Note that this is not
-    /// a true numerical offset but an opaque cookie that identifies a
-    /// position in the given stream.
+    /// Returns the “offset” of this directory entry. This is not a true
+    /// numerical offset but an opaque cookie that identifies a position in the
+    /// given stream.
     #[cfg(any(
         linux_like,
         solarish,

src/backend/libc/fs/syscalls.rs

@@ -2267,7 +2267,7 @@ fn times_to_attrlist(times: &Timestamps) -> io::Result<(c::size_t, [c::timespec;
 #[cfg(apple)]
 type Attrgroup = u32;
 
-/// Attribute list for use with `setattrlist`.
+/// Attribute list for use with [`setattrlist`].
 #[cfg(apple)]
 #[repr(C)]
 struct Attrlist {

src/backend/libc/fs/types.rs

@@ -332,16 +332,17 @@ bitflags! {
 
         /// `O_LARGEFILE`
         ///
-        /// Note that rustix and/or libc will automatically set this flag when appropriate on
-        /// `open(2)` and friends, thus typical users do not need to care about it.
-        /// It will may be reported in return of `fcntl_getfl`, though.
+        /// 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.
         #[cfg(any(linux_kernel, solarish))]
         const LARGEFILE = bitcast!(c::O_LARGEFILE);
 
         /// `O_ASYNC`, `FASYNC`
         ///
-        /// Note that this flag can't be used with [`rustix::fs::open`] family of functions, use
-        /// [`rustix::fs::fcntl_setfl`] instead
+        /// This flag can't be used with the [`rustix::fs::open`] family of
+        /// functions, use [`rustix::fs::fcntl_setfl`] instead.
         #[cfg(not(any(
             target_os = "aix",
             target_os = "espidf",
@@ -994,7 +995,7 @@ pub type StatFs = c::statfs;
 #[cfg(linux_like)]
 pub type StatFs = c::statfs64;
 
-/// `fsid_t` for use with `StatFs`.
+/// `fsid_t` for use with [`StatFs`].
 #[cfg(not(any(
     solarish,
     target_os = "espidf",

src/backend/libc/mount/types.rs

@@ -147,7 +147,7 @@ pub(crate) enum FsConfigCmd {
     /// `FSCONFIG_CMD_RECONFIGURE`
     Reconfigure = 7,
 
-    /// `FSCONFIG_CMD_CREATE_EXCL`
+    /// `FSCONFIG_CMD_CREATE_EXCL` (since Linux 6.6)
     CreateExclusive = 8,
 }
 

src/backend/libc/net/addr.rs

@@ -79,9 +79,8 @@ impl SocketAddrUnix {
     /// Construct a new unnamed address.
     ///
     /// The kernel will assign an abstract Unix-domain address to the socket
-    /// when you call [`bind_unix()`][crate::net::bind_unix]. You can
-    /// inspect the assigned name with
-    /// [`getsockname`][crate::net::getsockname].
+    /// when you call [`bind`][crate::net::bind]. You can inspect the assigned
+    /// name with [`getsockname`][crate::net::getsockname].
     ///
     /// # References
     ///  - [Linux]
@@ -238,6 +237,9 @@ impl fmt::Debug for SocketAddrUnix {
 }
 
 /// `struct sockaddr_storage`.
+///
+/// This type is guaranteed to be large enough to hold any encoded socket
+/// address.
 #[repr(transparent)]
 #[derive(Copy, Clone)]
 pub struct SocketAddrStorage(c::sockaddr_storage);

src/backend/libc/net/read_sockaddr.rs

@@ -101,7 +101,7 @@ pub(crate) unsafe fn read_sa_family(storage: *const c::sockaddr) -> u16 {
 #[cfg(apple)]
 #[inline]
 unsafe fn read_sun_path0(storage: *const c::sockaddr) -> u8 {
-    // In `read_ss_family` we assert that we know the layout of `sockaddr`.
+    // In `read_sa_family` we assert that we know the layout of `sockaddr`.
     storage
         .cast::<u8>()
         .add(super::addr::offsetof_sun_path())

src/backend/libc/net/sockopt.rs

@@ -1086,8 +1086,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_MMAP_OFFSETS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<c::xdp_mmap_offsets_v1>() {
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -1121,8 +1121,8 @@ pub(crate) fn xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets>
             size_of::<xdp_mmap_offsets>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_mmap_offsets are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_mmap_offsets are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
         let xpd_mmap_offsets = unsafe { value.assume_init() };
         Ok(XdpMmapOffsets {
             rx: XdpRingOffset {
@@ -1165,8 +1165,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_STATISTICS, &mut value, &mut optlen)?;
 
     if optlen as usize == size_of::<xdp_statistics_v1>() {
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,
@@ -1182,8 +1182,8 @@ pub(crate) fn xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics> {
             size_of::<xdp_statistics>(),
             "unexpected getsockopt size"
         );
-        // Safety: All members of xdp_statistics are u64 and thus are correctly
-        // initialized by `MaybeUninit::<xdp_statistics>::zeroed()`
+        // SAFETY: All members of xdp_statistics are `u64` and thus are
+        // correctly initialized by `MaybeUninit::<xdp_statistics>::zeroed()`.
         let xdp_statistics = unsafe { value.assume_init() };
         Ok(XdpStatistics {
             rx_dropped: xdp_statistics.rx_dropped,

src/backend/libc/system/syscalls.rs

@@ -83,7 +83,7 @@ pub(crate) fn setdomainname(name: &[u8]) -> io::Result<()> {
     }
 }
 
-// https://github.com/rust-lang/libc/pull/4212
+// <https://github.com/rust-lang/libc/pull/4212>
 #[cfg(target_os = "android")]
 pub(crate) fn setdomainname(name: &[u8]) -> io::Result<()> {
     syscall! {

src/backend/libc/termios/types.rs

@@ -1,3 +1,5 @@
+//! Types for the `termios` module.
+
 #![allow(non_camel_case_types)]
 
 #[cfg(not(target_os = "redox"))]