Miscellaneous documentation cleanups (#1036)

* Reword the documentation for `tcsendbreak`.

* Add documentation for `mount2`.

* Comment formatting cleanups.

Author: sunfishcode

src/backend/libc/fs/syscalls.rs

@@ -2282,7 +2282,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 {

src/backend/libc/net/sockopt.rs

@@ -1000,11 +1000,13 @@ pub(crate) fn set_xdp_rx_ring_size(fd: BorrowedFd<'_>, value: u32) -> io::Result
 #[cfg(target_os = "linux")]
 #[inline]
 pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets> {
-    // The kernel will write `xdp_mmap_offsets` or `xdp_mmap_offsets_v1` to the supplied pointer,
-    // depending on the kernel version. Both structs only contain u64 values.
-    // By using the larger of both as the parameter, we can shuffle the values to the non-v1 version
-    // returned by `get_xdp_mmap_offsets` while keeping the return type unaffected by the kernel
-    // version. This works because C will layout all struct members one after the other.
+    // The kernel will write `xdp_mmap_offsets` or `xdp_mmap_offsets_v1` to the
+    // supplied pointer, depending on the kernel version. Both structs only
+    // contain u64 values. By using the larger of both as the parameter, we can
+    // shuffle the values to the non-v1 version returned by
+    // `get_xdp_mmap_offsets` while keeping the return type unaffected by the
+    // kernel version. This works because C will layout all struct members one
+    // after the other.
 
     let mut optlen = core::mem::size_of::<xdp_mmap_offsets>().try_into().unwrap();
     debug_assert!(
@@ -1015,8 +1017,8 @@ pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffs
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_MMAP_OFFSETS, &mut value, &mut optlen)?;
 
     if optlen as usize == core::mem::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 {
@@ -1050,8 +1052,8 @@ pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffs
             core::mem::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 {
@@ -1094,8 +1096,8 @@ pub(crate) fn get_xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_STATISTICS, &mut value, &mut optlen)?;
 
     if optlen as usize == core::mem::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,
@@ -1111,8 +1113,8 @@ pub(crate) fn get_xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics
             core::mem::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/linux_raw/net/addr.rs

@@ -10,9 +10,8 @@ use crate::backend::c;
 use crate::ffi::CStr;
 use crate::{io, path};
 use core::cmp::Ordering;
-use core::fmt;
 use core::hash::{Hash, Hasher};
-use core::slice;
+use core::{fmt, slice};
 
 /// `struct sockaddr_un`
 #[derive(Clone)]

src/backend/linux_raw/net/netdevice.rs

@@ -3,8 +3,7 @@
 use crate::backend::io::syscalls::ioctl;
 use crate::fd::AsFd;
 use crate::io;
-use core::slice;
-use core::str;
+use core::{slice, str};
 use linux_raw_sys::ctypes::c_char;
 use linux_raw_sys::ioctl::SIOCGIFINDEX;
 #[cfg(feature = "alloc")]

src/backend/linux_raw/net/sockopt.rs

@@ -836,11 +836,13 @@ pub(crate) fn set_xdp_rx_ring_size(fd: BorrowedFd<'_>, value: u32) -> io::Result
 #[cfg(target_os = "linux")]
 #[inline]
 pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffsets> {
-    // The kernel will write `xdp_mmap_offsets` or `xdp_mmap_offsets_v1` to the supplied pointer,
-    // depending on the kernel version. Both structs only contain u64 values.
-    // By using the larger of both as the parameter, we can shuffle the values to the non-v1 version
-    // returned by `get_xdp_mmap_offsets` while keeping the return type unaffected by the kernel
-    // version. This works because C will layout all struct members one after the other.
+    // The kernel will write `xdp_mmap_offsets` or `xdp_mmap_offsets_v1` to the
+    // supplied pointer, depending on the kernel version. Both structs only
+    // contain u64 values. By using the larger of both as the parameter, we can
+    // shuffle the values to the non-v1 version returned by
+    // `get_xdp_mmap_offsets` while keeping the return type unaffected by the
+    // kernel version. This works because C will layout all struct members one
+    // after the other.
 
     let mut optlen = core::mem::size_of::<xdp_mmap_offsets>().try_into().unwrap();
     debug_assert!(
@@ -851,8 +853,8 @@ pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffs
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_MMAP_OFFSETS, &mut value, &mut optlen)?;
 
     if optlen as usize == core::mem::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 {
@@ -886,8 +888,8 @@ pub(crate) fn get_xdp_mmap_offsets(fd: BorrowedFd<'_>) -> io::Result<XdpMmapOffs
             core::mem::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 {
@@ -930,8 +932,8 @@ pub(crate) fn get_xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics
     getsockopt_raw(fd, c::SOL_XDP, c::XDP_STATISTICS, &mut value, &mut optlen)?;
 
     if optlen as usize == core::mem::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,
@@ -947,8 +949,8 @@ pub(crate) fn get_xdp_statistics(fd: BorrowedFd<'_>) -> io::Result<XdpStatistics
             core::mem::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/fs/mod.rs

@@ -167,10 +167,12 @@ impl StatExt for Stat {
     fn atime(&self) -> i64 {
         self.st_atime as i64
     }
+
     #[inline]
     fn mtime(&self) -> i64 {
         self.st_mtime as i64
     }
+
     #[inline]
     fn ctime(&self) -> i64 {
         self.st_ctime as i64

src/mount/mount_unmount.rs

@@ -3,12 +3,9 @@
 use crate::backend::mount::types::{
     InternalMountFlags, MountFlags, MountFlagsArg, MountPropagationFlags, UnmountFlags,
 };
-use crate::{
-    backend,
-    ffi::CStr,
-    io,
-    path::{self, option_into_with_c_str},
-};
+use crate::ffi::CStr;
+use crate::path::{self, option_into_with_c_str};
+use crate::{backend, io};
 
 /// `mount(source, target, filesystemtype, mountflags, data)`
 ///
@@ -43,6 +40,10 @@ pub fn mount<Source: path::Arg, Target: path::Arg, Fs: path::Arg, Data: path::Ar
 
 /// `mount2(source, target, filesystemtype, mountflags, data)`
 ///
+/// This is same as the [`mount`], except it adds support for
+/// the source, target, and data being omitted, and the data
+/// is passed as a `CStr` rather than a `path::Arg`.
+///
 /// # References
 ///  - [Linux]
 ///

src/net/netdevice.rs

@@ -1,12 +1,14 @@
 //! Low-level Linux network device access
 //!
-//! The methods in this module take a socket's file descriptor to communicate with
-//! the kernel in their ioctl call:
+//! The methods in this module take a socket's file descriptor to communicate
+//! with the kernel in their ioctl call:
 //! - glibc uses an `AF_UNIX`, `AF_INET`, or `AF_INET6` socket.
-//! The address family itself does not matter and glibc tries the next address family if socket creation with one fails.
+//! The address family itself does not matter and glibc tries the next address
+//! family if socket creation with one fails.
 //! - Android (bionic) uses an `AF_INET` socket.
 //! - Both create the socket with `SOCK_DGRAM|SOCK_CLOEXEC` type/flag.
-//! - The [man-pages] specify, that the ioctl calls "can be used on any socket's file descriptor regardless of the
+//! - The [man-pages] specify, that the ioctl calls "can be used on any
+//!   socket's file descriptor regardless of the
 //! family or type".
 //!
 //! # References
@@ -20,7 +22,8 @@ use crate::alloc::string::String;
 use crate::fd::AsFd;
 use crate::io;
 
-/// `ioctl(fd, SIOCGIFINDEX, ifreq)`—Returns the interface index for a given name.
+/// `ioctl(fd, SIOCGIFINDEX, ifreq)`—Returns the interface index for a given
+/// name.
 ///
 /// See the [module-level documentation] for information about `fd` usage.
 ///
@@ -35,7 +38,8 @@ pub fn name_to_index(fd: impl AsFd, if_name: &str) -> io::Result<u32> {
     crate::backend::net::netdevice::name_to_index(fd, if_name)
 }
 
-/// `ioctl(fd, SIOCGIFNAME, ifreq)`—Returns the interface name for a given index.
+/// `ioctl(fd, SIOCGIFNAME, ifreq)`—Returns the interface name for a given
+/// index.
 ///
 /// See the [module-level documentation] for information about `fd` usage.
 ///

src/net/send_recv/msg.rs

@@ -478,7 +478,8 @@ pub struct AncillaryDrain<'buf> {
 }
 
 impl<'buf> AncillaryDrain<'buf> {
-    /// Create an iterator for control messages that were received without [`RecvAncillaryBuffer`].
+    /// Create an iterator for control messages that were received without
+    /// [`RecvAncillaryBuffer`].
     ///
     /// # Safety
     ///

src/net/socket.rs

@@ -275,7 +275,8 @@ pub fn bind_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()>
     backend::net::syscalls::bind_unix(sockfd.as_fd(), addr)
 }
 
-/// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a XDP address.
+/// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a XDP
+/// address.
 ///
 /// # References
 ///  - [Linux]

src/net/types.rs

@@ -1465,8 +1465,8 @@ pub mod xdp {
         }
     }
 
-    // Constant needs to be cast because bindgen does generate a u32 but the struct expects a u16.
-    // https://github.com/torvalds/linux/blob/v6.6/include/uapi/linux/if_xdp.h#L15-L44
+    // Constant needs to be cast because bindgen does generate a u32 but the struct
+    // expects a u16. https://github.com/torvalds/linux/blob/v6.6/include/uapi/linux/if_xdp.h#L15-L44
     bitflags! {
         /// `XDP_*` constants for use in [`SockaddrXdp`].
         #[repr(transparent)]
@@ -1722,11 +1722,12 @@ pub mod xdp {
     /// Offset for mmapping completion ring.
     pub const XDP_UMEM_PGOFF_COMPLETION_RING: u64 = c::XDP_UMEM_PGOFF_COMPLETION_RING;
 
-    /// Offset used to shift the [`XdpDesc`] addr to the right to extract the address offset in
-    /// unaligned mode.
+    /// Offset used to shift the [`XdpDesc`] addr to the right to extract the
+    /// address offset in unaligned mode.
     pub const XSK_UNALIGNED_BUF_OFFSET_SHIFT: u64 = c::XSK_UNALIGNED_BUF_OFFSET_SHIFT as u64;
-    /// Mask used to binary `and` the [`XdpDesc`] addr to extract the address without the offset
-    /// carried in the upper 16 bits of the address in unaligned mode.
+    /// Mask used to binary `and` the [`XdpDesc`] addr to extract the address
+    /// without the offset carried in the upper 16 bits of the address in
+    /// unaligned mode.
     pub const XSK_UNALIGNED_BUF_ADDR_MASK: u64 = c::XSK_UNALIGNED_BUF_ADDR_MASK;
 }
 

src/process/pidfd.rs

@@ -30,8 +30,8 @@ pub fn pidfd_open(pid: Pid, flags: PidfdFlags) -> io::Result<OwnedFd> {
     backend::process::syscalls::pidfd_open(pid, flags)
 }
 
-/// `syscall(SYS_pidfd_send_signal, pidfd, sig, NULL, 0)`—Send a signal to a process
-/// specified by a file descriptor.
+/// `syscall(SYS_pidfd_send_signal, pidfd, sig, NULL, 0)`—Send a signal to a
+/// process specified by a file descriptor.
 ///
 /// # References
 ///  - [Linux]

src/termios/tc.rs

@@ -107,11 +107,13 @@ pub fn tcsetattr<Fd: AsFd>(
 
 /// `tcsendbreak(fd, 0)`—Transmit zero-valued bits.
 ///
-/// Also known as the `TCSBRK` operation with `ioctl`, with a duration of 0.
+/// This transmits zero-valued bits for at least 0.25 seconds.
 ///
-/// This function always uses an effective duration parameter of zero. For the
-/// equivalent of a `tcsendbreak` with a non-zero duration parameter, use
-/// `tcdrain`.
+/// This function does not have a `duration` parameter, and always uses the
+/// implementation-defined value, which transmits for at least 0.25 seconds.
+///
+/// Also known as the `TCSBRK` operation with `ioctl`, with a duration
+/// parameter of 0.
 ///
 /// # References
 ///  - [POSIX `tcsendbreak`]