Miscellaneous documentation cleanups. (#778)

Author: sunfishcode

examples/dup2_to_replace_stdio.rs

@@ -5,16 +5,17 @@
 fn main() -> std::io::Result<()> {
     use rustix::pipe::pipe;
     use rustix::stdio::{dup2_stdin, dup2_stdout};
-    use std::io::{BufRead, BufReader};
 
     // Create some new file descriptors that we'll use to replace stdio's file
     // descriptors with.
     let (reader, writer) = pipe()?;
 
-    // Use `dup2` to copy our new file descriptors over the stdio file descriptors.
+    // Use `dup2` to copy our new file descriptors over the stdio file
+    // descriptors.
     //
-    // Rustix has a plain `dup2` function too, but it requires a `&mut OwnedFd`,
-    // so these helper functions make it easier to use when replacing stdio fds.
+    // Rustix has a plain `dup2` function too, but it requires a
+    // `&mut OwnedFd`, so these helper functions make it easier to use when
+    // replacing stdio fds.
     dup2_stdin(&reader)?;
     dup2_stdout(&writer)?;
 
@@ -28,9 +29,9 @@ fn main() -> std::io::Result<()> {
 
     // And we can read from stdin, and it'll read from our pipe. It's a little
     // silly that we connected our stdout to our own stdin, but it's just an
-    // example :-).
+    // example 😀.
     let mut s = String::new();
-    BufReader::new(std::io::stdin()).read_line(&mut s)?;
+    std::io::stdin().read_line(&mut s)?;
     assert_eq!(s, "hello, world!\n");
 
     Ok(())

src/backend/libc/c.rs

@@ -1,3 +1,5 @@
+//! Libc and supplemental types and constants.
+
 #![allow(unused_imports)]
 
 // Import everything from libc, but we'll add some stuff and override some

src/backend/libc/event/epoll.rs

@@ -160,11 +160,11 @@ pub fn create(flags: CreateFlags) -> io::Result<OwnedFd> {
     unsafe { ret_owned_fd(c::epoll_create1(bitflags_bits!(flags))) }
 }
 
-/// `epoll_ctl(self, EPOLL_CTL_ADD, data, event)`—Adds an element to an
-/// epoll object.
+/// `epoll_ctl(self, EPOLL_CTL_ADD, data, event)`—Adds an element to an epoll
+/// object.
 ///
-/// This registers interest in any of the events set in `events` occurring
-/// on the file descriptor associated with `data`.
+/// This registers interest in any of the events set in `events` occurring on
+/// the file descriptor associated with `data`.
 ///
 /// If [`delete`] is not called on the I/O source passed into this function
 /// before the I/O source is `close`d, then the `epoll` will act as if the I/O
@@ -198,8 +198,8 @@ pub fn add(
     }
 }
 
-/// `epoll_ctl(self, EPOLL_CTL_MOD, target, event)`—Modifies an element in
-/// a given epoll object.
+/// `epoll_ctl(self, EPOLL_CTL_MOD, target, event)`—Modifies an element in a
+/// given epoll object.
 ///
 /// This sets the events of interest with `target` to `events`.
 #[doc(alias = "epoll_ctl")]
@@ -229,8 +229,8 @@ pub fn modify(
     }
 }
 
-/// `epoll_ctl(self, EPOLL_CTL_DEL, target, NULL)`—Removes an element in
-/// a given epoll object.
+/// `epoll_ctl(self, EPOLL_CTL_DEL, target, NULL)`—Removes an element in a
+/// given epoll object.
 #[doc(alias = "epoll_ctl")]
 pub fn delete(epoll: impl AsFd, source: impl AsFd) -> io::Result<()> {
     // SAFETY: We're calling `epoll_ctl` via FFI and we know how it
@@ -341,8 +341,8 @@ impl EventData {
 
     /// Return the value as a `u64`.
     ///
-    /// If the stored value was a pointer, the pointer is zero-extended to
-    /// a `u64`.
+    /// If the stored value was a pointer, the pointer is zero-extended to a
+    /// `u64`.
     #[inline]
     pub fn u64(self) -> u64 {
         unsafe { self.as_u64 }

src/backend/libc/event/poll_fd.rs

@@ -112,7 +112,7 @@ impl<'fd> PollFd<'fd> {
     /// Returns the ready events.
     #[inline]
     pub fn revents(&self) -> PollFlags {
-        // Use `unwrap()` here because in theory we know we know all the bits
+        // Use `.unwrap()` here because in theory we know we know all the bits
         // the OS might set here, but OS's have added extensions in the past.
         PollFlags::from_bits(self.pollfd.revents).unwrap()
     }
@@ -123,7 +123,7 @@ impl<'fd> AsFd for PollFd<'fd> {
     #[inline]
     fn as_fd(&self) -> BorrowedFd<'_> {
         // SAFETY: Our constructors and `set_fd` require `pollfd.fd` to be
-        // valid for the `fd lifetime.
+        // valid for the `'fd` lifetime.
         unsafe { BorrowedFd::borrow_raw(self.pollfd.fd) }
     }
 }
@@ -133,7 +133,7 @@ impl<'fd> AsSocket for PollFd<'fd> {
     #[inline]
     fn as_socket(&self) -> BorrowedFd<'_> {
         // SAFETY: Our constructors and `set_fd` require `pollfd.fd` to be
-        // valid for the `fd lifetime.
+        // valid for the `'fd` lifetime.
         unsafe { BorrowedFd::borrow_raw(self.pollfd.fd as RawFd) }
     }
 }

src/backend/libc/fs/inotify.rs

@@ -112,8 +112,8 @@ pub fn inotify_add_watch<P: crate::path::Arg>(
 
 /// `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.
+/// The watch descriptor provided should have previously been returned by
+/// [`inotify_add_watch`] and not previously have been removed.
 #[doc(alias = "inotify_rm_watch")]
 pub fn inotify_remove_watch(inot: BorrowedFd<'_>, wd: i32) -> io::Result<()> {
     // Android's `inotify_rm_watch` takes `u32` despite that

src/backend/libc/fs/makedev.rs

@@ -30,8 +30,8 @@ pub(crate) fn makedev(maj: u32, min: u32) -> Dev {
 #[cfg(all(target_os = "android", target_pointer_width = "32"))]
 #[inline]
 pub(crate) fn makedev(maj: u32, min: u32) -> Dev {
-    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit,
-    // so we do it ourselves.
+    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit, so we do
+    // it ourselves.
     ((u64::from(maj) & 0xffff_f000_u64) << 32)
         | ((u64::from(maj) & 0x0000_0fff_u64) << 8)
         | ((u64::from(min) & 0xffff_ff00_u64) << 12)
@@ -86,8 +86,8 @@ pub(crate) fn major(dev: Dev) -> u32 {
 #[cfg(all(target_os = "android", target_pointer_width = "32"))]
 #[inline]
 pub(crate) fn major(dev: Dev) -> u32 {
-    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit,
-    // so we do it ourselves.
+    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit, so we do
+    // it ourselves.
     (((dev >> 31 >> 1) & 0xffff_f000) | ((dev >> 8) & 0x0000_0fff)) as u32
 }
 
@@ -125,8 +125,8 @@ pub(crate) fn minor(dev: Dev) -> u32 {
 #[cfg(all(target_os = "android", target_pointer_width = "32"))]
 #[inline]
 pub(crate) fn minor(dev: Dev) -> u32 {
-    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit,
-    // so we do it ourselves.
+    // 32-bit Android's `dev_t` is 32-bit, but its `st_dev` is 64-bit, so we do
+    // it ourselves.
     (((dev >> 12) & 0xffff_ff00) | (dev & 0x0000_00ff)) as u32
 }
 

src/backend/libc/fs/syscalls.rs

@@ -128,8 +128,8 @@ pub(crate) fn open(path: &CStr, oflags: OFlags, mode: Mode) -> io::Result<OwnedF
         return open_via_syscall(path, oflags, mode);
     }
 
-    // On these platforms, `mode_t` is `u16` and can't be passed directly to
-    // a variadic function.
+    // On these platforms, `mode_t` is `u16` and can't be passed directly to a
+    // variadic function.
     #[cfg(any(
         apple,
         freebsdlike,
@@ -191,8 +191,8 @@ pub(crate) fn openat(
         return openat_via_syscall(dirfd, path, oflags, mode);
     }
 
-    // On these platforms, `mode_t` is `u16` and can't be passed directly to
-    // a variadic function.
+    // On these platforms, `mode_t` is `u16` and can't be passed directly to a
+    // variadic function.
     #[cfg(any(
         apple,
         freebsdlike,

src/backend/libc/fs/types.rs

@@ -249,6 +249,8 @@ bitflags! {
         const WRONLY = bitcast!(c::O_WRONLY);
 
         /// `O_RDWR`
+        ///
+        /// This is not equal to `RDONLY | WRONLY`. It's a distinct flag.
         const RDWR = bitcast!(c::O_RDWR);
 
         /// `O_NOCTTY`

src/backend/libc/time/syscalls.rs

@@ -109,7 +109,7 @@ pub(crate) fn clock_gettime(id: ClockId) -> Timespec {
         clock_gettime_old(id)
     }
 
-    // Use `unwrap()` here because `clock_getres` can fail if the clock itself
+    // Use `.unwrap()` here because `clock_getres` can fail if the clock itself
     // overflows a number of seconds, but if that happens, the monotonic clocks
     // can't maintain their invariants, or the realtime clocks aren't properly
     // configured.

src/backend/libc/time/types.rs

@@ -25,11 +25,12 @@ pub type Itimerspec = c::itimerspec;
 /// [`timerfd_settime`]: crate::time::timerfd_settime
 #[cfg(any(linux_kernel, target_os = "fuchsia"))]
 #[cfg(fix_y2038)]
-#[allow(missing_docs)]
 #[repr(C)]
 #[derive(Debug, Clone)]
 pub struct Itimerspec {
+    /// The interval of an interval timer.
     pub it_interval: Timespec,
+    /// Time remaining in the current interval.
     pub it_value: Timespec,
 }
 
@@ -116,10 +117,10 @@ bitflags! {
 pub enum TimerfdClockId {
     /// `CLOCK_REALTIME`—A clock that tells the “real” time.
     ///
-    /// This is a clock that tells the amount of time elapsed since the
-    /// Unix epoch, 1970-01-01T00:00:00Z. The clock is externally settable, so
-    /// it is not monotonic. Successive reads may see decreasing times, so it
-    /// isn't reliable for measuring durations.
+    /// This is a clock that tells the amount of time elapsed since the Unix
+    /// epoch, 1970-01-01T00:00:00Z. The clock is externally settable, so it is
+    /// not monotonic. Successive reads may see decreasing times, so it isn't
+    /// reliable for measuring durations.
     Realtime = bitcast!(c::CLOCK_REALTIME),
 
     /// `CLOCK_MONOTONIC`—A clock that tells an abstract time.