Cleanup all doc warnings

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: Bryant Mairs

src/sys/aio.rs

@@ -97,6 +97,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

@@ -100,8 +100,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

@@ -59,11 +59,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

@@ -76,7 +76,7 @@ impl FdSet {
 /// # Parameters
 ///
 /// * `nfds`: The highest file descriptor set in any of the passed `FdSet`s, plus 1. If `None`, this
-///   is calculated automatically by calling [`FdSet::highest`] on all descriptor sets and adding 1
+///   is calculated automatically by calling [`FdSet::highest`][1] on all descriptor sets and adding 1
 ///   to the maximum of that.
 /// * `readfds`: File descriptors to check for being ready to read.
 /// * `writefds`: File descriptors to check for being ready to write.
@@ -87,7 +87,8 @@ impl FdSet {
 /// # References
 ///
 /// [select(2)](http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html)
-/// [`FdSet::highest`]: struct.FdSet.html#method.highest
+///
+/// [1]: struct.FdSet.html#method.highest
 pub fn select<'a, N, R, W, E, T>(nfds: N,
                                  readfds: R,
                                  writefds: W,

src/unistd.rs

@@ -814,9 +814,10 @@ pub fn write(fd: RawFd, buf: &[u8]) -> Result<usize> {
     Errno::result(res).map(|r| r as usize)
 }
 
-/// Directive that tells [`lseek`] and [`lseek64`] what the offset is relative to.
-/// [`lseek`]: ./fn.lseek.html
-/// [`lseek64`]: ./fn.lseek64.html
+/// Directive that tells [`lseek`][1] and [`lseek64`][2] what the offset is relative to.
+///
+/// [1]: ./fn.lseek.html
+/// [2]: ./fn.lseek64.html
 #[repr(i32)]
 pub enum Whence {
     /// Specify an offset relative to the start of the file.
@@ -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) };
 
@@ -1124,12 +1125,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<()> {
@@ -1245,13 +1258,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<()> {
@@ -1280,7 +1306,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 {