Improved layout and wording of option accessor functions.

1 files changed, 16 insertions, 25 deletions

diff --git a/docs/man/nng_pipe_getopt.3.adoc b/docs/man/nng_pipe_getopt.3.adoc
index 5fc3a1ce..9bc7529e 100644
--- a/docs/man/nng_pipe_getopt.3.adoc
+++ b/docs/man/nng_pipe_getopt.3.adoc
@@ -48,9 +48,8 @@ vary, and many are documented in <<nng_options.5#,nng_options(5)>>.
 Additionally some transport-specific options and protocol-specific options are
 documented with the transports and protocols themselves.
 
-NOTE: All "`options`" on a pipe are read-only values, and intended to
-facilitate understanding the identity of an associated peer.
-Modification of options must be done on the listener or dialer using either
+NOTE: All "`options`" on a pipe are read-only values.
+Modification of options may be done before the pipe is created using
 `<<nng_listener_setopt.3#,nng_listener_setopt()>>` or
 `<<nng_dialer_getopt.3#,nng_dialer_setopt()>>`.
 
@@ -64,67 +63,59 @@ In all of these forms, the option _opt_ is retrieved from the pipe _p_.
 The details of the type, size, and semantics of the option will depend
 on the actual option, and will be documented with the option itself.
 
-==== `nng_pipe_getopt()`
-
+`nng_pipe_getopt()`::
 This is untyped, and can be used to retrieve the value of any option.
 A pointer to a buffer to receive the value in _val_, and the size of the
-buffer shall be stored at the location referenced by _valszp_.
-
+buffer shall be stored at the location referenced by _valszp_. +
+ +
 When the function returns, the actual size of the data copied (or that
 would have been copied if sufficient space were present) is stored at
 the location referenced by _valszp_.
 If the caller's buffer is not large enough to hold the entire object,
 then the copy is truncated.
 Therefore the caller should check for truncation by verifying that the
-size returned in _valszp_ does not exceed the original buffer size.
-
+size returned in _valszp_ does not exceed the original buffer size. +
+ +
 It is acceptable to pass `NULL` for _val_ if the value in _valszp_ is zero.
 This can be used to determine the size of the buffer needed to receive
 the object.
 
-TIP: Generally, it will be easier to use one of the typed forms instead.
-
-==== `nng_pipe_getopt_bool()`
+TIP: It may be easier to use one of the typed forms of this function.
 
+`nng_pipe_getopt_bool()`::
 This function is for options which take a Boolean (`bool`).
 The value will be stored at _bvalp_.
 
-==== `nng_pipe_getopt_int()`
-
+`nng_pipe_getopt_int()`::
 This function is for options which take an integer (`int`).
 The value will be stored at _ivalp_.
 
-==== `nng_pipe_getopt_ms()`
-
+`nng_pipe_getopt_ms()`::
 This function is used to retrieve time durations
 (`<<nng_duration.5#,nng_duration>>`) in milliseconds, which are stored in
 _durp_.
 
-==== `nng_pipe_getopt_ptr()`
+`nng_pipe_getopt_ptr()`::
 This function is used to retrieve a pointer, _ptr_, to structured data.
 The data referenced by _ptr_ is generally managed using other functions.
 Note that this form is somewhat special in that the object is generally
 not copied, but instead the *pointer* to the object is copied.
 
-==== `nng_pipe_getopt_size()`
-
+`nng_pipe_getopt_size()`::
 This function is used to retrieve a size into the pointer _zp_,
 typically for buffer sizes, message maximum sizes, and similar options.
 
-==== `nng_pipe_getopt_sockaddr()`
-
+`nng_pipe_getopt_sockaddr()`::
 This function is used to retrieve an `<<nng_sockaddr.5#,nng_sockaddr>>`
 into _sap_.
 
-==== `nng_pipe_getopt_string()`
-
+`nng_pipe_getopt_string()`::
 This function is used to retrieve a string into _strp_.
 This string is created from the source using `<<nng_strdup.3#,nng_strdup()>>`
 and consequently must be freed by the caller using
 `<<nng_strfree.3#,nng_strfree()>>` when it is no longer needed.
 
-==== `nng_pipe_getopt_uint64()`
-
+`nng_pipe_getopt_uint64()`::
 This function is used to retrieve a 64-bit unsigned value into the value
 referenced by _u64p_.
 This is typically used for options