fixes #293 nng_listener_getopt doc needs updating

Actually I updated all the option related documents, and fixed minor
markup issues on several others.

1 files changed, 39 insertions, 29 deletions

diff --git a/docs/man/nng_dialer_getopt.3.adoc b/docs/man/nng_dialer_getopt.3.adoc
index 8dad06d1..61aaa576 100644
--- a/docs/man/nng_dialer_getopt.3.adoc
+++ b/docs/man/nng_dialer_getopt.3.adoc
@@ -21,6 +21,8 @@ nng_dialer_getopt - get dialer option
 
 int nng_dialer_getopt(nng_dialer d, const char *opt, void *val, size_t *valszp);
 
+int nng_dialer_getopt_bool(nng_dialer d, const char *opt, bool *bvalp);
+
 int nng_dialer_getopt_int(nng_dialer d, const char *opt, int *ivalp);
 
 int nng_dialer_getopt_ms(nng_dialer d, const char *opt, nng_duration *durp);
@@ -34,22 +36,31 @@ int nng_dialer_getopt_uint64(nng_dialer d, const char *opt, uint64_t *u64p);
 
 == DESCRIPTION
 
+(((options, dialer)))
 The `nng_dialer_getopt()` functions are used to retrieve option values for
-the dialer _d_.
+the <<nng_dialer.5#,dialer>> _d_.
 The actual options that may be retrieved in this way
 vary, and many are documented in <<nng_options.5#,nng_options(5)>>.
-Additionally some transport-specific options are documented with the
-transports themselves.
+
+Additionally some transport-specific options and protocol-specific options
+are documented with the transports and protocols themselves.
+
+=== Forms
 
 In all of these forms, the option _opt_ is retrieved from the dialer _d_.
+The forms vary based on the type of the option they take.
+
+TIP: Generally, it will be easier to use one of the typed versions of this
+function.
+
+NOTE: No validation that the option is actually of the associated type is
+performed, so the caller must take care to use the *correct* typed form.
 
 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.
 
-=== Untyped Form
-
-The first form of this function, `nng_dialer_getopt()`, can be used to
-retrieve the value of any option.
+==== `nng_dialer_getopt()`
+This function is untyped and can be used to retrieve the value of any option.
 The caller must store 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_.
@@ -66,41 +77,39 @@ 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.
 
-=== Typed Forms
-
-Generally, it will be easier to use one of the typed forms instead.
-Note however that no validation that the option is actually of the associated
-type is performed, so the caller must take care to use the *correct* typed
-form.
+==== `nng_dialer_getopt_bool()`
+This function is for options which take a boolean (`bool`).
+The value will be stored at _ivalp_.
 
-The second form, `nng_dialer_getopt_int()`,
-is for options which take an integer (or boolean).
+==== `nng_dialer_getopt_int()`
+This function is for options which take an integer (`int`).
 The value will be stored at _ivalp_.
-For booleans the value will be eiher 0 (false) or 1 (true).
 
-The third form, `nng_dialer_getopt_ms()`, is used to retrieve time durations
+==== `nng_dialer_getopt_ms()`
+This function is used to retrieve time <<nng_duration.5#,durations>>
 (such as timeouts), stored in _durp_ as a number of milliseconds.
-(The special value `NNG_DUR_INFINITE` means an infinite amount of time, and
-the special value `NNG_DUR_DEFAULT` means a context-specific default.)
+(The special value ((`NNG_DUR_INFINITE`)) means an infinite amount of time, and
+the special value ((`NNG_DUR_DEFAULT`)) means a context-specific default.)
 
-The fourth form, `nng_dialer_getopt_ptr()`, is used to retrieve a
-pointer _ptr_ to structured data.
+==== `nng_dialer_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.
 
-The fifth form, `nng_dialer_getopt_size()`, is used to retrieve a size
-into the pointer _zp_, typically for buffer sizes, message maximum sizes, and
-similar options.
+==== `nng_dialer_getopt_size()`
+This function is used to retrieve a size into the pointer _zp_,
+typically for buffer sizes, message maximum sizes, and similar options.
 
-The sixth form, `nng_dialer_getopt_uint64()`, is used to retrieve a
-64-bit unsigned value into the value referenced by _u64p_.
-This is typically used for options
-related to identifiers, network numbers, and similar.
+==== `nng_dialer_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 related to identifiers, network
+numbers, and similar.
 
 == RETURN VALUES
 
-This function returns 0 on success, and non-zero otherwise.
+These functions returns 0 on success, and non-zero otherwise.
 
 == ERRORS
 
@@ -114,5 +123,6 @@ This function returns 0 on success, and non-zero otherwise.
 <<nng_dialer_setopt.3#,nng_dialer_setopt(3)>>
 <<nng_strerror.3#,nng_strerror(3)>>,
 <<nng_dialer.5#,nng_dialer(5)>>,
+<<nng_duration.5#,nng_duration(5)>>,
 <<nng_options.5#,nng_options(5)>>,
 <<nng.7#,nng(7)>>