Miscellaneous documentation cleanups. (#837)

Author: sunfishcode

src/fs/fd.rs

@@ -105,7 +105,7 @@ pub fn tell<Fd: AsFd>(fd: Fd) -> io::Result<u64> {
     backend::fs::syscalls::tell(fd.as_fd())
 }
 
-/// `fchmod(fd)`—Sets open file or directory permissions.
+/// `fchmod(fd, mode)`—Sets open file or directory permissions.
 ///
 /// This implementation does not support `O_PATH` file descriptors, even on
 /// platforms where the host libc emulates it.
@@ -122,7 +122,7 @@ pub fn fchmod<Fd: AsFd>(fd: Fd, mode: Mode) -> io::Result<()> {
     backend::fs::syscalls::fchmod(fd.as_fd(), mode)
 }
 
-/// `fchown(fd)`—Sets open file or directory ownership.
+/// `fchown(fd, owner, group)`—Sets open file or directory ownership.
 ///
 /// # References
 ///  - [POSIX]

src/fs/statx.rs

@@ -28,7 +28,7 @@ use compat::statx as _statx;
 /// # use std::io;
 /// # use rustix::fs::{AtFlags, StatxFlags};
 /// # use rustix::fd::BorrowedFd;
-/// /// Try to determine if the provided path is a mount root.  Will return `Ok(None)` if
+/// /// Try to determine if the provided path is a mount root. Will return `Ok(None)` if
 /// /// the kernel is not new enough to support statx() or [`libc::STATX_ATTR_MOUNT_ROOT`].
 /// fn is_mountpoint(root: BorrowedFd<'_>, path: &Path) -> io::Result<Option<bool>> {
 ///     use rustix::fs::{AtFlags, StatxFlags};

src/ioctl/mod.rs

@@ -160,7 +160,7 @@ pub unsafe trait Ioctl {
     /// making this `false` enables optimizations that can make the call
     /// faster. When in doubt, set this to `true`.
     ///
-    /// # SAFETY
+    /// # Safety
     ///
     /// This should only be set to `false` if the `ioctl` call does not mutate
     /// any data in the userspace. Undefined behavior may occur if this is

src/runtime.rs

@@ -2,8 +2,11 @@
 //! [origin].
 //!
 //! Do not use the functions in this module unless you've read all of their
-//! code, *and* you know all the relevant internal implementation details of
-//! any libc in the process they'll be used.
+//! code. They don't always behave the same way as functions with similar names
+//! in `libc`. Sometimes information about the differences is included in the
+//! Linux documentation under "C library/kernel differences" sections. And, if
+//! there is a libc in the process, these functions may have surprising
+//! interactions with it.
 //!
 //! These functions are for implementing thread-local storage (TLS), managing
 //! threads, loaded libraries, and other process-wide resources. Most of
@@ -143,7 +146,7 @@ pub unsafe fn exit_thread(status: i32) -> ! {
 ///
 /// This is equivalent to `_exit` and `_Exit` in libc.
 ///
-/// This does not all any `__cxa_atexit`, `atexit`, or any other destructors.
+/// This does not call any `__cxa_atexit`, `atexit`, or any other destructors.
 /// Most programs should use [`std::process::exit`] instead of calling this
 /// directly.
 ///

src/termios/tty.rs

@@ -54,7 +54,8 @@ fn _ttyname(dirfd: BorrowedFd<'_>, mut buffer: Vec<u8>) -> io::Result<CString> {
                 buffer.reserve(buffer.capacity() + 1); // use `Vec` reallocation strategy to grow capacity exponentially
             }
             Ok(len) => {
-                // SAFETY: assume the backend returns the length of the string excluding the NUL.
+                // SAFETY: assume the backend returns the length of the string excluding the
+                // NUL.
                 unsafe {
                     buffer.set_len(len + 1);
                 }