Document more things

Also, test rustdoc in CI, and demote missing_docs from a deny to a
warning (but still deny it in CI).

.cirrus.yml

@@ -2,6 +2,9 @@ cargo_cache:
   folder: $CARGO_HOME/registry
   fingerprint_script: cat Cargo.lock || echo ""
 
+env:
+  RUSTFLAGS: -D warnings
+  RUSTDOCFLAGS: -D warnings
 # Test FreeBSD in a full VM.  Test the i686 target too, in the
 # same VM.  The binary will be built in 32-bit mode, but will execute on a
 # 64-bit kernel and in a 64-bit environment.  Our tests don't execute any of
@@ -17,9 +20,11 @@ task:
   amd64_test_script:
     - . $HOME/.cargo/env
     - cargo test
+    - cargo doc --no-deps
   i386_test_script:
     - . $HOME/.cargo/env
     - cargo test --target i686-unknown-freebsd
+    - cargo doc --no-deps --target i686-unknown-freebsd
   before_cache_script: rm -rf $CARGO_HOME/registry/index
 
 # Test OSX and iOS in a full VM
@@ -48,7 +53,7 @@ task:
     RUST_TEST_THREADS: 1            # QEMU works best with 1 thread
     HOME: /tmp/home
     PATH: $HOME/.cargo/bin:$PATH
-    RUSTFLAGS: --cfg qemu
+    RUSTFLAGS: --cfg qemu -D warnings
   matrix:
     - name: Linux arm gnueabi
       env:
@@ -107,7 +112,7 @@ task:
       arm_container:
         image: rust:1.46
       env:
-        RUSTFLAGS: --cfg graviton
+        RUSTFLAGS: --cfg graviton -D warnings
         TARGET: aarch64-unknown-linux-gnu
     - name: Linux x86_64
       container:
@@ -125,6 +130,7 @@ task:
   script:
     - cargo build --target $TARGET --all-targets
     - cargo test --target $TARGET
+    - cargo doc --no-deps --target $TARGET
   before_cache_script: rm -rf $CARGO_HOME/registry/index
 
 # Tasks for cross-compiling, but no testing
@@ -210,6 +216,7 @@ task:
   script:
     - cargo +$TOOLCHAIN check --target $TARGET
     - cargo +$TOOLCHAIN check --all-targets --target $TARGET
+    - cargo +$TOOLCHAIN doc --no-deps --target $TARGET
   before_cache_script: rm -rf $CARGO_HOME/registry/index
 
 # Test that we can build with the lowest version of all dependencies.

src/lib.rs

@@ -11,7 +11,8 @@
 #![deny(unstable_features)]
 #![deny(missing_copy_implementations)]
 #![deny(missing_debug_implementations)]
-#![deny(missing_docs)]
+#![warn(missing_docs)]
+#![warn(rustdoc::broken_intra_doc_links)]
 
 // Re-exported external crates
 pub use libc;

src/sys/aio.rs

@@ -62,9 +62,9 @@ libc_enum! {
     pub enum LioOpcode {
         /// No operation
         LIO_NOP,
-        /// Write data as if by a call to [`aio_write`]
+        /// Write data as if by a call to [`AioCb::write`]
         LIO_WRITE,
-        /// Write data as if by a call to [`aio_read`]
+        /// Write data as if by a call to [`AioCb::read`]
         LIO_READ,
     }
 }

src/sys/mod.rs

@@ -49,7 +49,6 @@ pub mod mman;
 #[allow(missing_docs)]
 pub mod personality;
 
-#[allow(missing_docs)]
 pub mod pthread;
 
 #[cfg(any(target_os = "android",
@@ -70,22 +69,18 @@ pub mod quota;
 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"))]
@@ -107,7 +102,6 @@ pub mod stat;
           target_os = "macos",
           target_os = "openbsd"
 ))]
-#[allow(missing_docs)]
 pub mod statfs;
 
 pub mod statvfs;
@@ -122,13 +116,10 @@ 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"))]

src/sys/pthread.rs

@@ -1,3 +1,5 @@
+//! Low level threading primitives
+
 #[cfg(not(target_os = "redox"))]
 use crate::errno::Errno;
 #[cfg(not(target_os = "redox"))]
@@ -6,6 +8,7 @@ use crate::Result;
 use crate::sys::signal::Signal;
 use libc::{self, pthread_t};
 
+/// Identifies an individual thread.
 pub type Pthread = pthread_t;
 
 /// Obtain ID of the calling thread (see

src/sys/resource.rs

@@ -50,54 +50,88 @@ libc_enum! {
     #[non_exhaustive]
     pub enum Resource {
         #[cfg(not(any(target_os = "netbsd", target_os = "freebsd")))]
+        /// The maximum amount (in bytes) of virtual memory the process is
+        /// allowed to map.
         RLIMIT_AS,
+        /// The largest size (in bytes) core(5) file that may be created.
         RLIMIT_CORE,
+        /// The maximum amount of cpu time (in seconds) to be used by each
+        /// process.
         RLIMIT_CPU,
+        /// The maximum size (in bytes) of the data segment for a process
         RLIMIT_DATA,
+        /// The largest size (in bytes) file that may be created.
         RLIMIT_FSIZE,
+        /// The maximum number of open files for this process.
         RLIMIT_NOFILE,
+        /// The maximum size (in bytes) of the stack segment for a process.
         RLIMIT_STACK,
 
         #[cfg(target_os = "freebsd")]
+        /// The maximum number of kqueues this user id is allowed to create.
         RLIMIT_KQUEUES,
 
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        /// A limit on the combined number of flock locks and fcntl leases that
+        /// this process may establish.
         RLIMIT_LOCKS,
 
         #[cfg(any(target_os = "android", target_os = "freebsd", target_os = "openbsd", target_os = "linux"))]
+        /// The maximum size (in bytes) which a process may lock into memory
+        /// using the mlock(2) system call.
         RLIMIT_MEMLOCK,
 
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        /// A limit on the number of bytes that can be allocated for POSIX
+        /// message queues  for  the  real  user  ID  of  the  calling process.
         RLIMIT_MSGQUEUE,
 
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        /// A ceiling to which the process's nice value can be raised using
+        /// setpriority or nice.
         RLIMIT_NICE,
 
         #[cfg(any(target_os = "android", target_os = "freebsd", target_os = "openbsd", target_os = "linux"))]
+        /// The maximum number of simultaneous processes for this user id.
         RLIMIT_NPROC,
 
         #[cfg(target_os = "freebsd")]
+        /// The maximum number of pseudo-terminals this user id is allowed to
+        /// create.
         RLIMIT_NPTS,
 
         #[cfg(any(target_os = "android", target_os = "freebsd", target_os = "openbsd", target_os = "linux"))]
+        /// When there is memory pressure and swap is available, prioritize
+        /// eviction of a process' resident pages beyond this amount (in bytes).
         RLIMIT_RSS,
 
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        /// A ceiling on the real-time priority that may be set for this process
+        /// using sched_setscheduler and  sched_set‐ param.
         RLIMIT_RTPRIO,
 
         #[cfg(any(target_os = "linux"))]
+        /// A limit (in microseconds) on the amount of CPU time that a process
+        /// scheduled under a real-time scheduling policy may con‐ sume without
+        /// making a blocking system call.
         RLIMIT_RTTIME,
 
         #[cfg(any(target_os = "android", target_os = "linux"))]
+        /// A limit on the number of signals that may be queued for the real
+        /// user ID of the  calling  process.
         RLIMIT_SIGPENDING,
 
         #[cfg(any(target_os = "freebsd", target_os = "dragonfly"))]
+        /// The maximum size (in bytes) of socket buffer usage for this user.
         RLIMIT_SBSIZE,
 
         #[cfg(target_os = "freebsd")]
+        /// The maximum size (in bytes) of the swap space that may be reserved
+        /// or used by all of this user id's processes.
         RLIMIT_SWAP,
 
         #[cfg(target_os = "freebsd")]
+        /// An alias for RLIMIT_AS.
         RLIMIT_VMEM,
     }
 }

src/sys/select.rs

@@ -1,3 +1,4 @@
+//! Portably monitor a group of file descriptors for readiness.
 use std::iter::FusedIterator;
 use std::mem;
 use std::ops::Range;
@@ -11,11 +12,13 @@ use crate::sys::time::{TimeSpec, TimeVal};
 
 pub use libc::FD_SETSIZE;
 
+/// Contains a set of file descriptors used by [`select`]
 #[repr(transparent)]
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct FdSet(libc::fd_set);
 
 impl FdSet {
+    /// Create an empty `FdSet`
     pub fn new() -> FdSet {
         let mut fdset = mem::MaybeUninit::uninit();
         unsafe {
@@ -24,18 +27,22 @@ impl FdSet {
         }
     }
 
+    /// Add a file descriptor to an `FdSet`
     pub fn insert(&mut self, fd: RawFd) {
         unsafe { libc::FD_SET(fd, &mut self.0) };
     }
 
+    /// Remove a file descriptor from an `FdSet`
     pub fn remove(&mut self, fd: RawFd) {
         unsafe { libc::FD_CLR(fd, &mut self.0) };
     }
 
+    /// Test an `FdSet` for the presence of a certain file descriptor.
     pub fn contains(&self, fd: RawFd) -> bool {
         unsafe { libc::FD_ISSET(fd, &self.0) }
     }
 
+    /// Remove all file descriptors from this `FdSet`.
     pub fn clear(&mut self) {
         unsafe { libc::FD_ZERO(&mut self.0) };
     }

src/sys/sendfile.rs

@@ -1,3 +1,5 @@
+//! Send data from a file to a socket, bypassing userland.
+
 use cfg_if::cfg_if;
 use std::os::unix::io::RawFd;
 use std::ptr;