Miscellaneous documentation fixes. (#1144)

* Miscellaneous documentation fixes.

* More miscellaneous documentation fixes.

README.md

@@ -16,8 +16,8 @@
 </div>
 
 `rustix` provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like,
-Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends.
-It uses Rust references, slices, and return values instead of raw pointers, and
+Unix-like, Linux, and Winsock syscall-like APIs, with configurable backends. It
+uses Rust references, slices, and return values instead of raw pointers, and
 [I/O safety types] instead of raw file descriptors, providing memory safety,
 [I/O safety], and [provenance]. It uses `Result`s for reporting errors,
 [`bitflags`] instead of bare integer flags, an [`Arg`] trait with optimizations
@@ -46,14 +46,14 @@ more portable APIs built on this functionality, see the [`cap-std`], [`memfd`],
    Windows, and is portable to many OS's.
 
 The linux_raw backend is enabled by default on platforms which support it. To
-enable the libc backend instead, either enable the "use-libc" cargo feature,
-or set the `RUSTFLAGS` environment variable to `--cfg=rustix_use_libc` when
+enable the libc backend instead, either enable the "use-libc" cargo feature, or
+set the `RUSTFLAGS` environment variable to `--cfg=rustix_use_libc` when
 building.
 
 ## Cargo features
 
-The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled
-by default. The rest of the API is conditional with cargo feature flags:
+The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled by
+default. The rest of the API is conditional with cargo feature flags:
 
 | Name       | Description                                                    |
 | ---------- | -------------------------------------------------------------- |

src/backend/libc/fs/inotify.rs

@@ -1,4 +1,4 @@
-//! inotify support for working with inotifies
+//! inotify support for working with inotify objects.
 
 use crate::backend::c;
 use bitflags::bitflags;

src/backend/linux_raw/fs/inotify.rs

@@ -1,4 +1,4 @@
-//! inotify support for working with inotifies
+//! inotify support for working with inotify objects.
 
 use crate::backend::c;
 use bitflags::bitflags;

src/backend/linux_raw/mod.rs

@@ -5,7 +5,7 @@
 //! # Safety
 //!
 //! These files performs raw system calls, and sometimes passes them
-//! uninitialized memory buffers. The signatures in this file are currently
+//! uninitialized memory buffers. The signatures in this module are currently
 //! manually maintained and must correspond with the signatures of the actual
 //! Linux syscalls.
 //!

src/fs/at.rs

@@ -110,10 +110,10 @@ 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]: “A string that is used to
-            //   identify a file.”
+            // - “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.”

src/fs/inotify.rs

@@ -1,4 +1,4 @@
-//! inotify support for working with inotifies
+//! inotify support for working with inotify objects.
 //!
 //! # Examples
 //!
@@ -9,7 +9,7 @@
 //!
 //! # fn test() -> io::Result<()> {
 //! // Create an inotify object. In this example, we use `NONBLOCK` so that the
-//! // reader fails with `WOULDBLOCk` when no events are ready. Otherwise it
+//! // reader fails with `WOULDBLOCK` when no events are ready. Otherwise it
 //! // will block until at least one event is ready.
 //! let inotify = inotify::init(inotify::CreateFlags::NONBLOCK)?;
 //!
@@ -200,7 +200,7 @@ impl<'buf, Fd: AsFd> Reader<'buf, Fd> {
         // - This data is initialized by the check above.
         //   - Assumption: the kernel will not give us partial structs.
         // - Assumption: the kernel uses proper alignment between structs.
-        // - The starting pointer is aligned (performed in RawDir::new)
+        // - The starting pointer is aligned (performed in `Reader::new`).
         let event = unsafe { &*ptr.cast::<inotify_event>() };
 
         self.offset += size_of::<inotify_event>() + usize::try_from(event.len).unwrap();

src/fs/raw_dir.rs

@@ -213,7 +213,7 @@ impl<'buf, Fd: AsFd> RawDir<'buf, Fd> {
         // - This data is initialized by the check above.
         //   - Assumption: the kernel will not give us partial structs.
         // - Assumption: the kernel uses proper alignment between structs.
-        // - The starting pointer is aligned (performed in RawDir::new)
+        // - The starting pointer is aligned (performed in `RawDir::new`).
         let dirent = unsafe { &*dirent_ptr.cast::<linux_dirent64>() };
 
         self.offset += usize::from(dirent.d_reclen);

src/io/read_write.rs

@@ -1,4 +1,4 @@
-//! `read` and `write`, optionally positioned, optionally vectored
+//! `read` and `write`, optionally positioned, optionally vectored.
 
 #![allow(unsafe_code)]
 

src/process/chdir.rs

@@ -73,9 +73,9 @@ fn _getcwd(mut buffer: Vec<u8>) -> io::Result<CString> {
             }
             Ok(_) => {
                 // SAFETY:
-                // - "These functions return a null-terminated string"
-                // - [POSIX definition 3.375: String]: "A contiguous sequence
-                //   of bytes terminated by and including the first null byte."
+                // - “These functions return a null-terminated string”
+                // - [POSIX definition 3.375: String]: “A contiguous sequence
+                //   of bytes terminated by and including the first null byte.”
                 //
                 // Thus, there will be a single NUL byte at the end of the
                 // string.

src/process/id.rs

@@ -13,17 +13,8 @@ use alloc::vec::Vec;
 #[cfg(linux_kernel)]
 use backend::process::types::RawCpuid;
 
-/// The raw integer value of a Unix user ID.
-pub use crate::ugid::RawUid;
-
-/// The raw integer value of a Unix group ID.
-pub use crate::ugid::RawGid;
-
-/// The raw integer value of a Unix process ID.
-pub use crate::pid::RawPid;
-
-pub use crate::pid::Pid;
-pub use crate::ugid::{Gid, Uid};
+pub use crate::pid::{Pid, RawPid};
+pub use crate::ugid::{Gid, RawGid, RawUid, Uid};
 
 /// A Linux CPU ID.
 #[cfg(linux_kernel)]

src/runtime.rs

@@ -313,7 +313,7 @@ pub use backend::runtime::tls::StartupTlsInfo;
 /// > It is better you
 /// > Do not.
 ///
-/// - “Rules”, by Karla Kuskin
+/// — “Rules”, by Karla Kuskin
 ///
 /// [`MAP_SHARED`]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/mmap.html
 /// [not considered unsafe]: https://doc.rust-lang.org/reference/behavior-not-considered-unsafe.html#deadlocks

src/signal.rs

@@ -1,7 +1,7 @@
 use crate::backend::c;
 
-/// A signal number for use with [`kill_process`], [`kill_process_group`],
-/// and [`kill_current_process_group`].
+/// A signal number for use with [`kill_process`], [`kill_process_group`], and
+/// [`kill_current_process_group`].
 ///
 /// [`kill_process`]: crate::process::kill_process
 /// [`kill_process_group`]: crate::process::kill_process_group

src/termios/tty.rs

@@ -64,8 +64,8 @@ fn _ttyname(dirfd: BorrowedFd<'_>, mut buffer: Vec<u8>) -> io::Result<CString> {
 
                 // SAFETY:
                 // - “ttyname_r stores this pathname in the buffer buf”
-                // - [POSIX definition 3.271: Pathname]: “A string that is used
-                //   to identify a file.”
+                // - [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.”
                 //

src/termios/types.rs

@@ -126,7 +126,7 @@ impl Termios {
     /// constant value.
     #[inline]
     pub fn output_speed(&self) -> u32 {
-        // On Linux and BSDs, `input_speed` is the arbitrary integer speed.
+        // On Linux and BSDs, `output_speed` is the arbitrary integer speed.
         #[cfg(any(linux_kernel, bsd))]
         {
             debug_assert!(u32::try_from(self.output_speed).is_ok());
@@ -810,9 +810,9 @@ pub mod speed {
     /// `u32`.
     ///
     /// On BSD platforms, integer speed values are already the same as their
-    /// encoded values, and on Linux platforms, we use `TCGETS2`/`TCSETS2`
-    /// and the `c_ispeed`/`c_ospeed`` fields, except that on Linux on
-    /// PowerPC on QEMU, `TCGETS2`/`TCSETS2` don't set `c_ispeed`/`c_ospeed`.
+    /// encoded values, and on Linux platforms, we use `TCGETS2`/`TCSETS2` and
+    /// the `c_ispeed`/`c_ospeed` fields, except that on Linux on PowerPC on
+    /// QEMU, `TCGETS2`/`TCSETS2` don't set `c_ispeed`/`c_ospeed`.
     #[cfg(not(any(
         bsd,
         all(

src/thread/futex.rs

@@ -15,7 +15,7 @@
 //! # Ok(())
 //! # }
 //! ```
-
+//!
 //! # References
 //!  - [Linux `futex` system call]
 //!  - [Linux `futex` feature]