From e8879e310f3f1ca7277588de44204bf14eb1991c Mon Sep 17 00:00:00 2001 From: SteveLauC Date: Sun, 1 Sep 2024 17:35:48 +0800 Subject: [PATCH] docs: fix doc style & make clippy happy (#2478) * docs: fix doc style & make clippy happy * style: format code * docs: fix test doc style * style: format code --- src/mqueue.rs | 8 +++++--- src/sys/socket/sockopt.rs | 10 +++++++--- src/unistd.rs | 14 +++++++++----- test/test.rs | 7 ++++--- 4 files changed, 25 insertions(+), 14 deletions(-) diff --git a/src/mqueue.rs b/src/mqueue.rs index 7f9d687521..eea45be7a7 100644 --- a/src/mqueue.rs +++ b/src/mqueue.rs @@ -260,9 +260,11 @@ pub fn mq_getattr(mqd: &MqdT) -> Result { }) } -/// 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 { diff --git a/src/sys/socket/sockopt.rs b/src/sys/socket/sockopt.rs index 315f2ff43a..201097c614 100644 --- a/src/sys/socket/sockopt.rs +++ b/src/sys/socket/sockopt.rs @@ -303,13 +303,17 @@ 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, @@ -317,7 +321,7 @@ sockopt_impl!( 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, diff --git a/src/unistd.rs b/src/unistd.rs index e657d7ee07..e60e6cfc98 100644 --- a/src/unistd.rs +++ b/src/unistd.rs @@ -1002,13 +1002,14 @@ pub fn chown( 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: Fd, owner: Option, group: Option) -> Result<()> { use std::os::fd::AsRawFd; @@ -1303,12 +1304,13 @@ pub fn sethostname>(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; /// @@ -1316,6 +1318,8 @@ pub fn sethostname>(name: S) -> Result<()> { /// 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 { // The capacity is the max length of a hostname plus the NUL terminator. let mut buffer: Vec = Vec::with_capacity(256); diff --git a/test/test.rs b/test/test.rs index 6b970f8f09..3160ca7143 100644 --- a/test/test.rs +++ b/test/test.rs @@ -60,9 +60,10 @@ fn read_exact(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