From e7e98a4256bdb0a5ca6636c8c40be5bbefabd4d7 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Fri, 8 Jun 2018 14:50:57 -0700
Subject: fixes #517 nng_recv needs to document NNG_FLAG_NONBLOCK

---
 docs/man/nng_recv.3.adoc    | 40 +++++++++++++++++++++++-----------------
 docs/man/nng_recvmsg.3.adoc |  4 ++--
 2 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/docs/man/nng_recv.3.adoc b/docs/man/nng_recv.3.adoc
index f7c5f239..301eecc9 100644
--- a/docs/man/nng_recv.3.adoc
+++ b/docs/man/nng_recv.3.adoc
@@ -26,26 +26,32 @@ int nng_recv(nng_socket s, void *data, size_t *sizep int flags);
 
 The `nng_recv()` receives a message.
 
-If the special flag `NNG_FLAG_ALLOC` is not specified, then the caller must
-set _data_ to a buffer to receive the message body content, and must store
-the size of that buffer at the location pointed to by _sizep_.
+The _flags_ is a bit mask that may contain any of the following values:
+
+`NNG_FLAG_NONBLOCK`::
+  The function returns immediately, even if no message is available.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
+
+`NNG_FLAG_ALLOC`::
+  If this flag is present, then a "`((zero-copy))`" mode is used.
+  In this case the caller must set the value of _data_ to the location
+  of another pointer (of type `void *`), and the _sizep_ pointer must be set
+  to a location to receive the size of the message body.
+  The function will then allocate a message buffer
+  (as if by `<<nng_alloc.3#,nng_alloc()>>`), fill it with
+  the message body, and store it at the address referenced by _data_, and update
+  the size referenced by _sizep_.
+  The caller is responsible for disposing of the received buffer either by
+  the `<<nng_free.3#,nng_free()>>` function or passing the message (also
+  with the `NNG_FLAG_ALLOC` flag) in a call to `<<nng_send.3#,nng_send()>>`.
+
+If the special flag `NNG_FLAG_ALLOC` (see above) is not specified, then the
+caller must set _data_ to a buffer to receive the message body content,
+and must store the size of that buffer at the location pointed to by _sizep_.
 When the function returns, if it is successful, the size at _sizep_ will be
 updated with the actual message body length copied into _data_.
 
-If the special flag `NNG_FLAG_ALLOC` is present, then a "`((zero-copy))`"
-mode is used.
-In this case the caller must set the value of _data_ to the location
-of another pointer (of type `void *`), and the _sizep_ pointer must be set
-to a location to receive the size of the message body.
-The function will then allocate a message buffer
-(as if by `<<nng_alloc.3#,nng_alloc()>>`), fill it with
-the message body, and store it at the address referenced by _data_, and update
-the size referenced by _sizep_.
-When this flag is present, the caller assumes
-responsibility for disposing of the received buffer either by the function
-`<<nng_free.3#,nng_free()>>` or reusing the message for sending (with the same
-size) in a call to `<<nng_send.3#,nng_send()>>`.
-
 NOTE: The semantics of what receiving a message means vary from protocol to
 protocol, so examination of the protocol documentation is encouraged.
 (For example, with a <<nng_req.7#,_req_>> socket a message may only be received
diff --git a/docs/man/nng_recvmsg.3.adoc b/docs/man/nng_recvmsg.3.adoc
index 8876c716..d8900c84 100644
--- a/docs/man/nng_recvmsg.3.adoc
+++ b/docs/man/nng_recvmsg.3.adoc
@@ -34,8 +34,8 @@ The _flags_ may contain the following value:
 
 `NNG_FLAG_NONBLOCK`::
   The function returns immediately, even if no message is available.
-  Without   this flag, the function will wait until a message is received
-  by the socket   _s_, or any configured timer expires.
+  Without this flag, the function will wait until a message is received
+  by the socket _s_, or any configured timer expires.
 
 NOTE: The semantics of what receiving a message means vary from protocol to
 protocol, so examination of the protocol documentation is encouraged.
-- 
cgit v1.2.3-70-g09d2