Miscellaneous documentation cleanups (#1036)

sunfishcode · web-flow · commit b494d287c5e0 · 2024-03-19T13:13:58.000-07:00
* Reword the documentation for `tcsendbreak`.

* Add documentation for `mount2`.

* Comment formatting cleanups.
diff --git a/src/backend/libc/fs/syscalls.rs b/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 {
diff --git a/src/backend/libc/net/sockopt.rs b/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,
diff --git a/src/backend/linux_raw/net/addr.rs b/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)]
diff --git a/src/backend/linux_raw/net/netdevice.rs b/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")]
diff --git a/src/backend/linux_raw/net/sockopt.rs b/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,
diff --git a/src/fs/mod.rs b/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
diff --git a/src/mount/mount_unmount.rs b/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]
 ///
diff --git a/src/net/netdevice.rs b/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.
 ///
diff --git a/src/net/send_recv/msg.rs b/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
     ///
diff --git a/src/net/socket.rs b/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]
diff --git a/src/net/types.rs b/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;
 }
 
diff --git a/src/process/pidfd.rs b/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]
diff --git a/src/termios/tc.rs b/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`]

Original file line number	Diff line number	Diff line change
`@@ -2282,7 +2282,8 @@ pub(crate) fn lgetxattr(path: &CStr, name: &CStr, value: &mut [u8]) -> io::Resul`
`2282`	`2282`
`2283`	`2283`	`#[cfg(apple)]`
`2284`	`2284`	`{`
`2285`		`- // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass null instead.`
	`2285`	`+ // Passing an empty to slice to getxattr leads to ERANGE on macOS. Pass null`
	`2286`	`+ // instead.`
`2286`	`2287`	`let ptr = if value.is_empty() {`
`2287`	`2288`	`core::ptr::null_mut()`
`2288`	`2289`	`} else {`
Original file line number	Diff line number	Diff line change
`@@ -167,10 +167,12 @@ impl StatExt for Stat {`
`167`	`167`	`fn atime(&self) -> i64 {`
`168`	`168`	`self.st_atime as i64`
`169`	`169`	`}`
	`170`	`+`
`170`	`171`	`#[inline]`
`171`	`172`	`fn mtime(&self) -> i64 {`
`172`	`173`	`self.st_mtime as i64`
`173`	`174`	`}`
	`175`	`+`
`174`	`176`	`#[inline]`
`175`	`177`	`fn ctime(&self) -> i64 {`
`176`	`178`	`self.st_ctime as i64`
Original file line number	Diff line number	Diff line change
`@@ -478,7 +478,8 @@ pub struct AncillaryDrain<'buf> {`
`478`	`478`	`}`
`479`	`479`
`480`	`480`	`impl<'buf> AncillaryDrain<'buf> {`
`481`		- /// Create an iterator for control messages that were received without [`RecvAncillaryBuffer`].
	`481`	`+ /// Create an iterator for control messages that were received without`
	`482`	+ /// [`RecvAncillaryBuffer`].
`482`	`483`	`///`
`483`	`484`	`/// # Safety`
`484`	`485`	`///`
Original file line number	Diff line number	Diff line change
`@@ -275,7 +275,8 @@ pub fn bind_unix<Fd: AsFd>(sockfd: Fd, addr: &SocketAddrUnix) -> io::Result<()>`
`275`	`275`	`backend::net::syscalls::bind_unix(sockfd.as_fd(), addr)`
`276`	`276`	`}`
`277`	`277`
`278`		-/// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a XDP address.
	`278`	+/// `bind(sockfd, addr, sizeof(struct sockaddr_un))`—Binds a socket to a XDP
	`279`	`+/// address.`
`279`	`280`	`///`
`280`	`281`	`/// # References`
`281`	`282`	`/// - [Linux]`