Add & document msg_capacity, msg_reserve (#1458)

* Add & document msg_capacity, msg_reserve

* reserve/capacity code style

* Documentation references to reserve/capacity

1 files changed, 7 insertions, 8 deletions

diff --git a/docs/man/nng_msg_realloc.3.adoc b/docs/man/nng_msg_realloc.3.adoc
index 4d57921b..bf407289 100644
--- a/docs/man/nng_msg_realloc.3.adoc
+++ b/docs/man/nng_msg_realloc.3.adoc
@@ -29,14 +29,12 @@ a body of length _size_.
 This message attempts to avoid extra allocations,
 and will reuse the existing memory when possible.
 
-TIP: One way to further reduce message allocations is to allocate a message
-larger than needed, then use this function or
-xref:nng_msg_chop.3.adoc[`nng_msg_chop()`] to reduce the message size
-to that actually needed.
-The extra space left
-over will still be present in the message, so that when the message size
-needs to grow due to this function or xref:nng_msg_append.3.adoc[`nng_msg_append()`]
-no actual memory allocations need to take place.
+TIP: `nng_msg_realloc` is suitable for creating space for direct writing of data.
+When appending many small pieces of data to a message using xref:nng_msg_append.3.adoc[`nng_msg_append()`],
+allocations may be reduced by first using xref:nng_msg_reserve.3.adoc[`nng_msg_reserve()`]
+to create sufficient space.
+In any case, reallocating or appending to a message is guaranteed to succeed if the resulting
+body length is less than xref:nng_msg_capacity.3.adoc[`nng_msg_capacity()`]. 
 
 NOTE: Pointers to message body and header content obtained prior to this
 function must not be in use, as the underlying memory used for the message
@@ -54,6 +52,7 @@ This function returns 0 on success, and non-zero otherwise.
 == SEE ALSO
 
 [.text-left]
+xref:nng_msg_reserve.3.adoc[nng_msg_reserve(3)],
 xref:nng_msg_alloc.3.adoc[nng_msg_alloc(3)],
 xref:nng_msg_append.3.adoc[nng_msg_append(3)],
 xref:nng_msg_body.3.adoc[nng_msg_body(3)],