Merge #806

806: Cleanup all doc warnings r=asomers a=Susurrus

With the impending switch to Pulldown as the default doc generator, warnings
have been enabled for incompatible syntax. This fixes all of said warnings.

Author: bors[bot]

src/sys/aio.rs

@@ -98,6 +98,7 @@ impl<'a> AioCb<'a> {
     /// Constructs a new `AioCb` with no associated buffer.
     ///
     /// The resulting `AioCb` structure is suitable for use with `AioCb::fsync`.
+    ///
     /// * `fd`  File descriptor.  Required for all aio functions.
     /// * `prio` If POSIX Prioritized IO is supported, then the operation will
     /// be prioritized at the process's priority level minus `prio`

src/sys/mman.rs

@@ -101,8 +101,7 @@ libc_bitflags!{
 libc_enum!{
     /// Usage information for a range of memory to allow for performance optimizations by the kernel.
     ///
-    /// Used by [`madvise`].
-    /// [`madvise`]: ./fn.madvise.html
+    /// Used by [`madvise`](./fn.madvise.html).
     #[repr(i32)]
     pub enum MmapAdvise {
         /// No further special treatment. This is the default.

src/sys/quota.rs

@@ -60,11 +60,11 @@ libc_enum!{
         QFMT_VFS_OLD,
         /// Use the standard VFS v0 quota format.
         ///
-        /// Handles 32-bit UIDs/GIDs and quota limits up to 2^42 bytes/2^32 inodes.
+        /// Handles 32-bit UIDs/GIDs and quota limits up to 2<sup>32</sup> bytes/2<sup>32</sup> inodes.
         QFMT_VFS_V0,
         /// Use the VFS v1 quota format.
         ///
-        /// Handles 32-bit UIDs/GIDs and quota limits of 2^64 bytes/2^64 inodes.
+        /// Handles 32-bit UIDs/GIDs and quota limits of 2<sup>64</sup> bytes/2<sup>64</sup> inodes.
         QFMT_VFS_V1,
     }
 }

src/sys/select.rs

@@ -88,6 +88,7 @@ impl FdSet {
 /// # References
 ///
 /// [select(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html)
+///
 /// [`FdSet::highest`]: struct.FdSet.html#method.highest
 pub fn select<'a, N, R, W, E, T>(nfds: N,
                                  readfds: R,

src/unistd.rs

@@ -815,6 +815,7 @@ pub fn write(fd: RawFd, buf: &[u8]) -> Result<usize> {
 }
 
 /// Directive that tells [`lseek`] and [`lseek64`] what the offset is relative to.
+///
 /// [`lseek`]: ./fn.lseek.html
 /// [`lseek64`]: ./fn.lseek64.html
 #[repr(i32)]
@@ -847,7 +848,7 @@ pub enum Whence {
 
 /// Move the read/write file offset.
 ///
-/// See also [lseek(2)(http://pubs.opengroup.org/onlinepubs/9699919799/functions/lseek.html)
+/// See also [lseek(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/lseek.html)
 pub fn lseek(fd: RawFd, offset: libc::off_t, whence: Whence) -> Result<libc::off_t> {
     let res = unsafe { libc::lseek(fd, offset, whence as i32) };
 
@@ -1143,12 +1144,24 @@ pub fn getgroups() -> Result<Vec<Gid>> {
 /// specific user and group. For example, given the user `www-data` with UID
 /// `33` and the group `backup` with the GID `34`, one could switch the user as
 /// follows:
-/// ```
+///
+/// ```rust,no_run
+/// # use std::error::Error;
+/// # use nix::unistd::*;
+/// #
+/// # fn try_main() -> Result<(), Box<Error>> {
 /// let uid = Uid::from_raw(33);
 /// let gid = Gid::from_raw(34);
 /// setgroups(&[gid])?;
 /// setgid(gid)?;
 /// setuid(uid)?;
+/// #
+/// #     Ok(())
+/// # }
+/// #
+/// # fn main() {
+/// #     try_main().unwrap();
+/// # }
 /// ```
 #[cfg(not(any(target_os = "ios", target_os = "macos")))]
 pub fn setgroups(groups: &[Gid]) -> Result<()> {
@@ -1264,13 +1277,26 @@ pub fn getgrouplist(user: &CStr, group: Gid) -> Result<Vec<Gid>> {
 /// UID and GID for the user in the system's password database (usually found
 /// in `/etc/passwd`). If the `www-data` user's UID and GID were `33` and `33`,
 /// respectively, one could switch the user as follows:
-/// ```
+///
+/// ```rust,no_run
+/// # use std::error::Error;
+/// # use std::ffi::CString;
+/// # use nix::unistd::*;
+/// #
+/// # fn try_main() -> Result<(), Box<Error>> {
 /// let user = CString::new("www-data").unwrap();
 /// let uid = Uid::from_raw(33);
 /// let gid = Gid::from_raw(33);
 /// initgroups(&user, gid)?;
 /// setgid(gid)?;
 /// setuid(uid)?;
+/// #
+/// #     Ok(())
+/// # }
+/// #
+/// # fn main() {
+/// #     try_main().unwrap();
+/// # }
 /// ```
 #[cfg(not(any(target_os = "ios", target_os = "macos")))]
 pub fn initgroups(user: &CStr, group: Gid) -> Result<()> {
@@ -1299,7 +1325,7 @@ pub fn pause() -> Result<()> {
 
 /// Suspend execution for an interval of time
 ///
-/// See also [sleep(2)(http://pubs.opengroup.org/onlinepubs/009695399/functions/sleep.html#tag_03_705_05)
+/// See also [sleep(2)](http://pubs.opengroup.org/onlinepubs/009695399/functions/sleep.html#tag_03_705_05)
 // Per POSIX, does not fail
 #[inline]
 pub fn sleep(seconds: libc::c_uint) -> c_uint {