docs: fix doc style & make clippy happy (nix-rust#2478)

* docs: fix doc style & make clippy happy

* style: format code

* docs: fix test doc style

* style: format code

src/mqueue.rs

@@ -260,9 +260,11 @@ pub fn mq_getattr(mqd: &MqdT) -> Result<MqAttr> {
     })
 }
 
-/// Set the attributes of the message queue. Only `O_NONBLOCK` can be set, everything else will be ignored
-/// Returns the old attributes
-/// It is recommend to use the `mq_set_nonblock()` and `mq_remove_nonblock()` convenience functions as they are easier to use
+/// Set the attributes of the message queue. Only `O_NONBLOCK` can be set,
+/// everything else will be ignored. Returns the old attributes.
+///
+/// It is recommend to use the `mq_set_nonblock()` and `mq_remove_nonblock()`
+/// convenience functions as they are easier to use.
 ///
 /// [Further reading](https://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_setattr.html)
 pub fn mq_setattr(mqd: &MqdT, newattr: &MqAttr) -> Result<MqAttr> {

src/sys/socket/sockopt.rs

@@ -303,21 +303,25 @@ sockopt_impl!(
 #[cfg(feature = "net")]
 sockopt_impl!(
     #[cfg_attr(docsrs, doc(cfg(feature = "net")))]
+    /// Used to disable Nagle's algorithm.
+    /// 
+    /// Nagle's algorithm:
+    /// 
     /// Under most circumstances, TCP sends data when it is presented; when
     /// outstanding data has not yet been acknowledged, it gathers small amounts
     /// of output to be sent in a single packet once an acknowledgement is
     /// received.  For a small number of clients, such as window systems that
     /// send a stream of mouse events which receive no replies, this
-    /// packetization may cause significant delays.  The boolean option
-    /// TCP_NODELAY defeats this algorithm.
+    /// packetization may cause significant delays.  The boolean option, when
+    /// enabled, defeats this algorithm.
     TcpNoDelay,
     Both,
     libc::IPPROTO_TCP,
     libc::TCP_NODELAY,
     bool
 );
 sockopt_impl!(
-    /// When enabled,  a close(2) or shutdown(2) will not return until all
+    /// When enabled, a close(2) or shutdown(2) will not return until all
     /// queued messages for the socket have been successfully sent or the
     /// linger timeout has been reached.
     Linger,

src/unistd.rs

@@ -1002,13 +1002,14 @@ pub fn chown<P: ?Sized + NixPath>(
     Errno::result(res).map(drop)
 }
 
-/// Change the ownership of the file referred to by the open file descriptor `fd` to be owned by
-/// the specified `owner` (user) and `group` (see
-/// [fchown(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fchown.html)).
+/// Change the ownership of the file referred to by the open file descriptor
+/// `fd` to be owned by the specified `owner` (user) and `group`.
 ///
 /// The owner/group for the provided file will not be modified if `None` is
 /// provided for that argument.  Ownership change will be attempted for the path
 /// only if `Some` owner/group is provided.
+///
+/// See also [`fchown(2)`](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fchown.html).
 #[inline]
 pub fn fchown<Fd: std::os::fd::AsFd>(fd: Fd, owner: Option<Uid>, group: Option<Gid>) -> Result<()> {
     use std::os::fd::AsRawFd;
@@ -1303,19 +1304,22 @@ pub fn sethostname<S: AsRef<OsStr>>(name: S) -> Result<()> {
 }
 
 /// Get the host name and store it in an internally allocated buffer, returning an
-/// `OsString` on success (see
-/// [gethostname(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/gethostname.html)).
+/// `OsString` on success.
 ///
 /// This function call attempts to get the host name for the running system and
 /// store it in an internal buffer, returning it as an `OsString` if successful.
 ///
+/// # Examples
+///
 /// ```no_run
 /// use nix::unistd;
 ///
 /// let hostname = unistd::gethostname().expect("Failed getting hostname");
 /// let hostname = hostname.into_string().expect("Hostname wasn't valid UTF-8");
 /// println!("Hostname: {}", hostname);
 /// ```
+///
+/// See also [gethostname(2)](https://pubs.opengroup.org/onlinepubs/9699919799/functions/gethostname.html).
 pub fn gethostname() -> Result<OsString> {
     // The capacity is the max length of a hostname plus the NUL terminator.
     let mut buffer: Vec<u8> = Vec::with_capacity(256);

test/test.rs

@@ -60,9 +60,10 @@ fn read_exact<Fd: AsFd>(f: Fd, buf: &mut [u8]) {
     }
 }
 
-/// Any test that creates child processes or can be affected by child processes must grab this mutex, regardless
-/// of what it does with those children. It must hold the mutex until the
-/// child processes are waited upon.
+/// Any test that creates child processes or can be affected by child processes
+/// must grab this mutex, regardless of what it does with those children.
+///
+/// It must hold the mutex until the child processes are waited upon.
 pub static FORK_MTX: Mutex<()> = Mutex::new(());
 /// Any test that changes the process's current working directory must grab
 /// the RwLock exclusively.  Any process that cares about the current