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, 49 insertions, 34 deletions

diff --git a/docs/man/nng_dialer_setopt.3.adoc b/docs/man/nng_dialer_setopt.3.adoc
index 311a6123..1bec71b2 100644
--- a/docs/man/nng_dialer_setopt.3.adoc
+++ b/docs/man/nng_dialer_setopt.3.adoc
@@ -22,6 +22,8 @@ nng_dialer_setopt - set dialer option
 int nng_dialer_setopt(nng_dialer d, const char *opt, const void *val,
     size_t valsz);
 
+int nng_dialer_setopt_bool(nng_dialer d, const char *opt, bool bval);
+
 int nng_dialer_setopt_int(nng_dialer d, const char *opt, int ival);
 
 int nng_dialer_setopt_ms(nng_dialer d, const char *opt, nng_duration dur);
@@ -37,64 +39,76 @@ int nng_dialer_setopt_uint64(nng_dialer d, const char *opt, uint64_t u64);
 
 == DESCRIPTION
 
+(((options, dialer)))
 The `nng_dialer_setopt()` functions are used to configure options for
-the dialer _d_.
+the <<nng_dialer.5#,dialer>> _d_.
 The actual options that may be configured 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.
 
+NOTE: Once a dialer has started, it is generally not possible to change
+it's configuration.
+
+=== Forms
+
 In all of these forms, the option _opt_ is configured on the dialer _d_.
 
 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.
 
-The first form of this function, `nng_dialer_setopt()`, can be used to
-configure any arbitrary data.
-The _val_ pointer addresses the data to copy, and _valsz_ is the
-size of the objected located at _val_.
-
-Generally, it will be easier to use one of the typed forms instead.
+TIP: Generally, it will be easier to use one of the typed forms instead.
 
-The second form, `nng_dialer_setopt_int()`,
-is for options which take an integer (or boolean).  The _ival_
-is passed to the option.  For booleans pass either 0 (false) or 1 (true).
+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 third form, `nng_dialer_setopt_ms()`, is used to configure time durations
-(such as timeouts).
-The duration _dur_ is an integer number of milliseconds.  (The special value
-`NNG_DUR_INFINITE` means an infinite amount of time.)
+==== `nng_dialer_setopt()`
+This function is untyped, and can be used to configure any arbitrary data.
+The _val_ pointer addresses the data to copy, and _valsz_ is the
+size of the objected located at _val_.
 
-The fourth form, `nng_dialer_setopt_ptr()`, is used to pass a
-pointer _ptr_ to structured data.  The data referenced by _ptr_ is
-generally managed by other functions.
-For example, TLS configuration objects
-(<<nng_tls_config_alloc.3tls#,`nng_tls_config_alloc()`>>) can be passed this way.
+==== `nng_dialer_setopt_bool()`
+This function is for options which take a boolean (`bool`).
+The _bval_ is passed to the option.
+
+==== `nng_dialer_setopt_int()`
+This function is for options which take an integer (`int`).
+The _ival_ is passed to the option.
+
+==== `nng_dialer_setopt_ms()`
+This function is used to configure time durations (such as timeouts) using
+type <<nng_duration.5#,`nng_duration`>>.
+The duration _dur_ is an integer number of milliseconds.
+
+==== `nng_dialer_setopt_ptr()`
+This function is used to pass a pointer, _ptr_, to structured data.
+The data referenced by _ptr_ is generally managed by other functions.
+For example, TLS configuration objects created with
+(<<nng_tls_config_alloc.3tls#,`nng_tls_config_alloc()`>>)
+can be passed this way.
 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_setopt_size()`, is used to pass a size
-specified by _z_, typically for buffer sizes, message maximum sizes, and
-similar options.
+==== `nng_dialer_setopt_size()`
+This function is used to configure a size, _z_, typically for buffer sizes,
+message maximum sizes, and similar options.
 
-The sixth form, `nng_dialer_setopt_string()`, is used to pass a string
-_str_. 
+==== `nng_dialer_setopt_string()`
+This function is used to pass configure a string, _str_.
 Strings passed this way must be legal UTF-8 or ASCII strings, terminated
 with a `NUL` (`\0`) byte.
-(Other constraints may apply as well, see the
-documentation for _opt_ for details.)
+(Other constraints may apply as well, see the documentation for each option
+for details.)
 
-The seventh form, `nng_dialer_setopt_uint64()`, is used to configure
-the 64-bit unsigned value in _u64_.
-This is typically used for options
-related to identifiers, network numbers, and similar.
-
-NOTE: Once a dialer has started, it is generally not possible to change
-it's configuration.
+==== `nng_dialer_setopt_uint64()`
+This function is used to configure a 64-bit unsigned value, _u64_.
+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 return 0 on success, and non-zero otherwise.
 
 == ERRORS
 
@@ -110,5 +124,6 @@ This function returns 0 on success, and non-zero otherwise.
 <<nng_dialer_getopt.3#,nng_dialer_getopt(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)>>