From 5b0b047de33e8f2cd44b7fd5b9a0aedb0c469c9c Mon Sep 17 00:00:00 2001
From: Nicolas Dusart <dusartnicolas@gmail.com>
Date: Mon, 17 Jul 2017 10:52:21 +0200
Subject: [PATCH] Document `MsgFlags` constants

---
 src/sys/socket/mod.rs | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/src/sys/socket/mod.rs b/src/sys/socket/mod.rs
index 4624260374..3d824f19ff 100644
--- a/src/sys/socket/mod.rs
+++ b/src/sys/socket/mod.rs
@@ -72,14 +72,51 @@ bitflags!(
 // Flags for send/recv and their relatives
 libc_bitflags!{
     pub flags MsgFlags: libc::c_int {
+        /// Sends or requests out-of-band data on sockets that support this notion
+        /// (e.g., of type [`Stream`](enum.SockType.html)); the underlying protocol must also
+        /// support out-of-band data.
         MSG_OOB,
+        /// Peeks at an incoming message. The data is treated as unread and the next
+        /// [`recv()`](fn.recv.html)
+        /// or similar function shall still return this data.
         MSG_PEEK,
+        /// Enables nonblocking operation; if the operation would block,
+        /// `EAGAIN` or `EWOULDBLOCK` is returned.  This provides similar
+        /// behavior to setting the `O_NONBLOCK` flag
+        /// (via the [`fcntl`](../../fcntl/fn.fcntl.html)
+        /// `F_SETFL` operation), but differs in that `MSG_DONTWAIT` is a per-
+        /// call option, whereas `O_NONBLOCK` is a setting on the open file
+        /// description (see [open(2)](http://man7.org/linux/man-pages/man2/open.2.html)),
+        /// which will affect all threads in
+        /// the calling process and as well as other processes that hold
+        /// file descriptors referring to the same open file description.
         MSG_DONTWAIT,
+        /// Receive flags: Control Data was discarded (buffer too small)
         MSG_CTRUNC,
+        /// For raw ([`Packet`](addr/enum.AddressFamily.html)), Internet datagram
+        /// (since Linux 2.4.27/2.6.8),
+        /// netlink (since Linux 2.6.22) and UNIX datagram (since Linux 3.4)
+        /// sockets: return the real length of the packet or datagram, even
+        /// when it was longer than the passed buffer. Not implemented for UNIX
+        /// domain ([unix(7)](https://linux.die.net/man/7/unix)) sockets.
+        ///
+        /// For use with Internet stream sockets, see [tcp(7)](https://linux.die.net/man/7/tcp).
         MSG_TRUNC,
+        /// Terminates a record (when this notion is supported, as for
+        /// sockets of type [`SeqPacket`](enum.SockType.html)).
         MSG_EOR,
+        /// This flag specifies that queued errors should be received from
+        /// the socket error queue. (For more details, see
+        /// [recvfrom(2)](https://linux.die.net/man/2/recvfrom))
         #[cfg(any(target_os = "linux", target_os = "android"))]
         MSG_ERRQUEUE,
+        /// Set the `close-on-exec` flag for the file descriptor received via a UNIX domain
+        /// file descriptor using the `SCM_RIGHTS` operation (described in
+        /// [unix(7)](https://linux.die.net/man/7/unix)).
+        /// This flag is useful for the same reasons as the `O_CLOEXEC` flag of
+        /// [open(2)](https://linux.die.net/man/2/open).
+        ///
+        /// Only used in [`recvmsg`](fn.recvmsg.html) function.
         #[cfg(any(target_os = "linux", target_os = "android"))]
         MSG_CMSG_CLOEXEC,
     }