Miscellaneous documentation fixes. (#1144)

* Miscellaneous documentation fixes.

* More miscellaneous documentation fixes.

Author: sunfishcode

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)]