Merge #1507 #1508

1507: Forbid dead code again r=asomers a=asomers

The old problems with bitflags no longer apply

1508: More rust docs r=asomers a=asomers

Switch from allow(missing_docs) to deny(missing_docs), which should
gradually help us moving forward.  Also, add a few missing docs, such as
for sched and aio.

Co-authored-by: Alan Somers <asomers@gmail.com>

Author: bors[bot]

src/env.rs

@@ -1,3 +1,4 @@
+//! Environment variables
 use cfg_if::cfg_if;
 use std::fmt;
 

src/lib.rs

@@ -5,15 +5,13 @@
 #![crate_name = "nix"]
 #![cfg(unix)]
 #![allow(non_camel_case_types)]
-// latest bitflags triggers a rustc bug with cross-crate macro expansions causing dead_code
-// warnings even though the macro expands into something with allow(dead_code)
-#![allow(dead_code)]
 #![cfg_attr(test, deny(warnings))]
 #![recursion_limit = "500"]
 #![deny(unused)]
 #![deny(unstable_features)]
 #![deny(missing_copy_implementations)]
 #![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
 
 // Re-exported external crates
 pub use libc;
@@ -23,13 +21,14 @@ pub use libc;
 
 // Public crates
 #[cfg(not(target_os = "redox"))]
+#[allow(missing_docs)]
 pub mod dir;
 pub mod env;
+#[allow(missing_docs)]
 pub mod errno;
-#[deny(missing_docs)]
 pub mod features;
+#[allow(missing_docs)]
 pub mod fcntl;
-#[deny(missing_docs)]
 #[cfg(any(target_os = "android",
           target_os = "dragonfly",
           target_os = "freebsd",
@@ -42,6 +41,7 @@ pub mod fcntl;
 pub mod ifaddrs;
 #[cfg(any(target_os = "android",
           target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod kmod;
 #[cfg(any(target_os = "android",
           target_os = "freebsd",
@@ -52,23 +52,24 @@ pub mod mount;
           target_os = "fushsia",
           target_os = "linux",
           target_os = "netbsd"))]
+#[allow(missing_docs)]
 pub mod mqueue;
-#[deny(missing_docs)]
 #[cfg(not(target_os = "redox"))]
 pub mod net;
-#[deny(missing_docs)]
 pub mod poll;
-#[deny(missing_docs)]
 #[cfg(not(any(target_os = "redox", target_os = "fuchsia")))]
 pub mod pty;
 pub mod sched;
 pub mod sys;
+#[allow(missing_docs)]
 pub mod time;
 // This can be implemented for other platforms as soon as libc
 // provides bindings for them.
 #[cfg(all(target_os = "linux",
           any(target_arch = "x86", target_arch = "x86_64")))]
+#[allow(missing_docs)]
 pub mod ucontext;
+#[allow(missing_docs)]
 pub mod unistd;
 
 /*
@@ -101,11 +102,17 @@ pub type Result<T> = result::Result<T, Errno>;
 /// ones.
 pub type Error = Errno;
 
+/// Common trait used to represent file system paths by many Nix functions.
 pub trait NixPath {
+    /// Is the path empty?
     fn is_empty(&self) -> bool;
 
+    /// Length of the path in bytes
     fn len(&self) -> usize;
 
+    /// Execute a function with this path as a `CStr`.
+    ///
+    /// Mostly used internally by Nix.
     fn with_nix_path<T, F>(&self, f: F) -> Result<T>
         where F: FnOnce(&CStr) -> T;
 }

src/mount/bsd.rs

@@ -347,6 +347,7 @@ impl<'a> Nmount<'a> {
         self
     }
 
+    /// Create a new `Nmount` struct with no options
     pub fn new() -> Self {
         Self::default()
     }

src/mount/mod.rs

@@ -1,7 +1,10 @@
+//! Mount file systems
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 mod linux;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub use self::linux::*;
 
 #[cfg(any(target_os = "dragonfly",

src/sched.rs

@@ -1,3 +1,7 @@
+//! Execution scheduling
+//!
+//! See Also
+//! [sched.h](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sched.h.html)
 use crate::{Errno, Result};
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
@@ -16,33 +20,70 @@ mod sched_linux_like {
     // For some functions taking with a parameter of type CloneFlags,
     // only a subset of these flags have an effect.
     libc_bitflags! {
+        /// Options for use with [`clone`]
         pub struct CloneFlags: c_int {
+            /// The calling process and the child process run in the same
+            /// memory space.
             CLONE_VM;
+            /// The caller and the child process share the same  filesystem
+            /// information.
             CLONE_FS;
+            /// The calling process and the child process share the same file
+            /// descriptor table.
             CLONE_FILES;
+            /// The calling process and the child process share the same table
+            /// of signal handlers.
             CLONE_SIGHAND;
+            /// If the calling process is being traced, then trace the child
+            /// also.
             CLONE_PTRACE;
+            /// The execution of the calling process is suspended until the
+            /// child releases its virtual memory resources via a call to
+            /// execve(2) or _exit(2) (as with vfork(2)).
             CLONE_VFORK;
+            /// The parent of the new child  (as returned by getppid(2))
+            /// will be the same as that of the calling process.
             CLONE_PARENT;
+            /// The child is placed in the same thread group as the calling
+            /// process.
             CLONE_THREAD;
+            /// The cloned child is started in a new mount namespace.
             CLONE_NEWNS;
+            /// The child and the calling process share a single list of System
+            /// V semaphore adjustment values
             CLONE_SYSVSEM;
-            CLONE_SETTLS;
-            CLONE_PARENT_SETTID;
-            CLONE_CHILD_CLEARTID;
+            // Not supported by Nix due to lack of varargs support in Rust FFI
+            // CLONE_SETTLS;
+            // Not supported by Nix due to lack of varargs support in Rust FFI
+            // CLONE_PARENT_SETTID;
+            // Not supported by Nix due to lack of varargs support in Rust FFI
+            // CLONE_CHILD_CLEARTID;
+            /// Unused since Linux 2.6.2
+            #[deprecated(since = "0.23.0", note = "Deprecated by Linux 2.6.2")]
             CLONE_DETACHED;
+            /// A tracing process cannot force `CLONE_PTRACE` on this child
+            /// process.
             CLONE_UNTRACED;
-            CLONE_CHILD_SETTID;
+            // Not supported by Nix due to lack of varargs support in Rust FFI
+            // CLONE_CHILD_SETTID;
+            /// Create the process in a new cgroup namespace.
             CLONE_NEWCGROUP;
+            /// Create the process in a new UTS namespace.
             CLONE_NEWUTS;
+            /// Create the process in a new IPC namespace.
             CLONE_NEWIPC;
+            /// Create the process in a new user namespace.
             CLONE_NEWUSER;
+            /// Create the process in a new PID namespace.
             CLONE_NEWPID;
+            /// Create the process in a new network namespace.
             CLONE_NEWNET;
+            /// The new process shares an I/O context with the calling process.
             CLONE_IO;
         }
     }
 
+    /// Type for the function executed by [`clone`].
     pub type CloneCb<'a> = Box<dyn FnMut() -> isize + 'a>;
 
     /// CpuSet represent a bit-mask of CPUs.
@@ -212,12 +253,18 @@ mod sched_linux_like {
         Errno::result(res).map(Pid::from_raw)
     }
 
+    /// disassociate parts of the process execution context
+    ///
+    /// See also [unshare(2)](https://man7.org/linux/man-pages/man2/unshare.2.html)
     pub fn unshare(flags: CloneFlags) -> Result<()> {
         let res = unsafe { libc::unshare(flags.bits()) };
 
         Errno::result(res).map(drop)
     }
 
+    /// reassociate thread with a namespace
+    ///
+    /// See also [setns(2)](https://man7.org/linux/man-pages/man2/setns.2.html)
     pub fn setns(fd: RawFd, nstype: CloneFlags) -> Result<()> {
         let res = unsafe { libc::setns(fd, nstype.bits()) };
 

src/sys/aio.rs

@@ -60,8 +60,11 @@ libc_enum! {
     #[repr(i32)]
     #[non_exhaustive]
     pub enum LioOpcode {
+        /// No operation
         LIO_NOP,
+        /// Write data as if by a call to [`aio_write`]
         LIO_WRITE,
+        /// Write data as if by a call to [`aio_read`]
         LIO_READ,
     }
 }
@@ -840,6 +843,7 @@ unsafe impl<'a> Sync for LioCb<'a> {}
 
 #[cfg(not(any(target_os = "ios", target_os = "macos")))]
 impl<'a> LioCb<'a> {
+    /// Are no [`AioCb`]s contained?
     pub fn is_empty(&self) -> bool {
         self.aiocbs.is_empty()
     }

src/sys/mod.rs

@@ -1,3 +1,4 @@
+//! Mostly platform-specific functionality
 #[cfg(any(target_os = "dragonfly",
           target_os = "freebsd",
           target_os = "ios",
@@ -7,6 +8,7 @@
 pub mod aio;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod epoll;
 
 #[cfg(any(target_os = "dragonfly",
@@ -15,9 +17,11 @@ pub mod epoll;
           target_os = "macos",
           target_os = "netbsd",
           target_os = "openbsd"))]
+#[allow(missing_docs)]
 pub mod event;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod eventfd;
 
 #[cfg(any(target_os = "android",
@@ -34,14 +38,18 @@ pub mod eventfd;
 pub mod ioctl;
 
 #[cfg(target_os = "linux")]
+#[allow(missing_docs)]
 pub mod memfd;
 
 #[cfg(not(target_os = "redox"))]
+#[allow(missing_docs)]
 pub mod mman;
 
 #[cfg(target_os = "linux")]
+#[allow(missing_docs)]
 pub mod personality;
 
+#[allow(missing_docs)]
 pub mod pthread;
 
 #[cfg(any(target_os = "android",
@@ -51,35 +59,44 @@ pub mod pthread;
           target_os = "macos",
           target_os = "netbsd",
           target_os = "openbsd"))]
+#[allow(missing_docs)]
 pub mod ptrace;
 
 #[cfg(target_os = "linux")]
 pub mod quota;
 
 #[cfg(any(target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod reboot;
 
 #[cfg(not(any(target_os = "redox", target_os = "fuchsia", target_os = "illumos")))]
+#[allow(missing_docs)]
 pub mod resource;
 
 #[cfg(not(target_os = "redox"))]
+#[allow(missing_docs)]
 pub mod select;
 
 #[cfg(any(target_os = "android",
           target_os = "freebsd",
           target_os = "ios",
           target_os = "linux",
           target_os = "macos"))]
+#[allow(missing_docs)]
 pub mod sendfile;
 
+#[allow(missing_docs)]
 pub mod signal;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod signalfd;
 
 #[cfg(not(target_os = "redox"))]
+#[allow(missing_docs)]
 pub mod socket;
 
+#[allow(missing_docs)]
 pub mod stat;
 
 #[cfg(any(target_os = "android",
@@ -90,25 +107,34 @@ pub mod stat;
           target_os = "macos",
           target_os = "openbsd"
 ))]
+#[allow(missing_docs)]
 pub mod statfs;
 
 pub mod statvfs;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod sysinfo;
 
+#[allow(missing_docs)]
 pub mod termios;
 
+#[allow(missing_docs)]
 pub mod time;
 
+#[allow(missing_docs)]
 pub mod uio;
 
+#[allow(missing_docs)]
 pub mod utsname;
 
+#[allow(missing_docs)]
 pub mod wait;
 
 #[cfg(any(target_os = "android", target_os = "linux"))]
+#[allow(missing_docs)]
 pub mod inotify;
 
 #[cfg(target_os = "linux")]
+#[allow(missing_docs)]
 pub mod timerfd;

src/sys/signal.rs

@@ -1,7 +1,7 @@
 // Portions of this file are Copyright 2014 The Rust Project Developers.
 // See https://www.rust-lang.org/policies/licenses.
 
-///! Operating system signals.
+//! Operating system signals.
 
 use crate::{Error, Result};
 use crate::errno::Errno;