Improved option docs slightly.

6 files changed, 64 insertions, 88 deletions

diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc
index 4b8e75d3..1ad2d3f4 100644
--- a/docs/man/nng_req.7.adoc
+++ b/docs/man/nng_req.7.adoc
@@ -97,8 +97,7 @@ The following protocol-specific option is available.
 
 ((`NNG_OPT_REQ_RESENDTIME`))::
 
-   This read/write option is a duration (`<<nng_duration.5#,nng_duration>>`)
-   representing a relative number of milliseconds.
+   (`<<nng_duration.5#,nng_duration>>`)
    When a new request is started, a timer of this duration is also started.
    If no reply is received before this timer expires, then the request will
    be resent.
diff --git a/docs/man/nng_surveyor.7.adoc b/docs/man/nng_surveyor.7.adoc
index 8bee4fd9..259003e4 100644
--- a/docs/man/nng_surveyor.7.adoc
+++ b/docs/man/nng_surveyor.7.adoc
@@ -94,9 +94,7 @@ The following protocol-specific options is available.
 
 ((`NNG_OPT_SURVEYOR_SURVEYTIME`))::
 
-   This read/write option is an `<<nng_duration.5#,nng_duration>>`
-   representing a positive number of milliseconds that following surveys
-   will last.
+   (`<<nng_duration.5#,nng_duration>>`) Duration of surveys.
    When a new survey is started, a timer of this duration is also started.
    Any responses arriving this time will be discarded.
    Attempts to receive
diff --git a/docs/man/nng_tcp.7.adoc b/docs/man/nng_tcp.7.adoc
index c0c4a5f0..c06070ee 100644
--- a/docs/man/nng_tcp.7.adoc
+++ b/docs/man/nng_tcp.7.adoc
@@ -90,20 +90,17 @@ the actual structure is either of type
 === Transport Options
 
 ((`NNG_OPT_TCP_KEEPALIVE`))::
-
-This option is used to configure TCP keep-alives.
-The value is of type `bool`, and defaults to `false`.
+(`bool`) Enable TCP keep-alives, defaults to `false`.
 
 ((`NNG_OPT_TCP_NODELAY`))::
-
-This option is used to configure Nagle's algorithm.
+(`bool`) Disable Nagle's algorithm.
 When enabled (`false`), the underlying TCP stream will attempt
 to buffer and coalesce messages before sending them on, waiting
 a short interval to improve buffering and reduce the overhead
 caused by sending too-small messages.
 This comes at a cost to latency, and is not recommended with modern
 high speed networks.
-The value is of type `bool` and defaults to `true`.
+Defaults to `true`.
 
 == SEE ALSO
 
diff --git a/docs/man/nng_tls.7.adoc b/docs/man/nng_tls.7.adoc
index 59aa77f2..bb9eb614 100644
--- a/docs/man/nng_tls.7.adoc
+++ b/docs/man/nng_tls.7.adoc
@@ -119,66 +119,59 @@ The following transport options are available.
 Note that setting these must be done before the transport is started.
 
 ((`NNG_OPT_TCP_KEEPALIVE`))::
-
-This option is used to configure TCP keep-alives.
-The value is of type `bool`, and defaults to `false`.
+(`bool`) Enable TCP keep-alives, defaults to `false`.
 
 ((`NNG_OPT_TCP_NODELAY`))::
-
-This option is used to configure Nagle's algorithm.
+(`bool`) Disable Nagle's algorithm.
 When enabled (`false`), the underlying TCP stream will attempt
 to buffer and coalesce messages before sending them on, waiting
 a short interval to improve buffering and reduce the overhead
 caused by sending too-small messages.
 This comes at a cost to latency, and is not recommended with modern
 high speed networks.
-The value is of type `bool` and defaults to `true`.
+Defaults to `true`.
 
 ((`NNG_OPT_TLS_CONFIG`))::
-
-This option is used on an endpoint to access the underlying TLS
+(`nng_tls_config *`)
+The underlying TLS
 configuration object.
-The value is of type `nng_tls_config *`.
-If the value is not `NULL`, a hold is placed on the underlying
-configuration object before returning it (see
-`<<nng_tls_config_hold.3tls#,nng_tls_config_hold()>>`).
-The caller should release the object with
+A hold is placed on the underlying
+configuration object before returning it.
+The caller should release the hold with
 `<<nng_tls_config_free.3tls#,nng_tls_config_free()>>` when it no
 longer needs the TLS configuration object.
 
 TIP: Use this option when advanced TLS configuration is required.
 
 ((`NNG_OPT_TLS_CA_FILE`))::
-
-This is a write-only option used to load certificates associated
-associated private key from a file.
+(string) Write-only option naming a file containing certificates to
+use for peer validation.
 See `<<nng_tls_config_ca_file.3tls#,nng_tls_config_ca_file()>>` for more
 information.
 
 ((`NNG_OPT_TLS_CERT_KEY_FILE`))::
-
-This is a write-only option used to load the local certificate and
-associated private key from a file. The private key used must be
-unencrypted. (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying
+(string) Write-only option naming a file containing the local certificate and
+associated private key.
+The private key used must be unencrypted.
+(Use the `NNG_OPT_TLS_CONFIG` option to access the underlying
 TLS configuration if more advanced configuration is needed.)
 See `<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>` for more
 information.
 
 ((`NNG_OPT_TLS_AUTH_MODE`))::
-
-This is a write-only option used to configure the authentication mode
-used.  It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`,
-`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`.
+(`int`) Write-only option used to configure the authentication mode used.
+Must be one of
+`NNG_TLS_AUTH_MODE_NONE`,
+`NNG_TLS_AUTH_MODE_REQUIRED`, or
+`NNG_TLS_AUTH_MODE_OPTIONAL`.
 See `<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>` for
 more details.
 
 ((`NNG_OPT_TLS_VERIFIED`))::
 
-This is a read-only option which returns a Boolean value (integer 0 or 1).
-It will true (1) if the remote peer has been properly verified using TLS
-authentication, or false (0) otherwise.
-This option may return incorrect
-results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`.
+(`bool`) Whether the remote peer has been properly verified using TLS
+authentication.
+May return incorrect results if peer authentication is disabled.
 
 == SEE ALSO
 
diff --git a/docs/man/nng_ws.7.adoc b/docs/man/nng_ws.7.adoc
index 9d4ef497..581da044 100644
--- a/docs/man/nng_ws.7.adoc
+++ b/docs/man/nng_ws.7.adoc
@@ -114,26 +114,24 @@ only available for `wss://` endpoints.
 
 ((`NNG_OPT_WS_REQUEST_HEADERS`))::
 
-This value is a string, consisting of multiple lines terminated
+(string) Concentation of multiple lines terminated
 by CRLF sequences, that can be used to add further headers to the
 HTTP request sent when connecting.
 This option can be set on dialers, and retrieved from pipes.
 
 ((`NNG_OPT_WS_RESPONSE_HEADERS`))::
 
-This value is a string, consisting of multiple lines terminated
+(string) Concatenation of multiple lines terminated
 by CRLF sequences, that can be used to add further headers to the
 HTTP response sent when connecting.
 This option can be set on listeners, and retrieved from pipes.
 
 ((`NNG_OPT_TLS_CONFIG`))::
 
-(opaque) This option is used on an endpoint to access the underlying TLS
+(`nng_tls_config *`) The underlying TLS
 configuration object for `wss://` endpoints.
-The value is of type `nng_tls_config *`.
 A hold is placed on the underlying
-configuration object before returning it (see
-`<<nng_tls_config_hold.3tls#,nng_tls_config_hold()>>`).
+configuration object before returning it.
 The caller should release the object with
 `<<nng_tls_config_free.3tls#,nng_tls_config_free()>>` when it no
 longer needs the TLS configuration.
@@ -141,16 +139,14 @@ longer needs the TLS configuration.
 TIP: Use this option when advanced TLS configuration is required.
 
 ((`NNG_OPT_TLS_CA_FILE`))::
-
-(string) This is a write-only option used to load certificates associated
-associated private key from a file.
+(string) Write-only option naming a file containing certificates to
+use for peer validation.
 See `<<nng_tls_config_ca_file.3tls#,nng_tls_config_ca_file()>>` for more
 information.
 
 ((`NNG_OPT_TLS_CERT_KEY_FILE`))::
-
-(string) This is a write-only option used to load the local certificate and
-associated private key from a file.
+(string) Write-only option naming a file containing the local certificate and
+associated private key.
 The private key used must be unencrypted.
 (Use the `NNG_OPT_TLS_CONFIG` option to access the underlying
 TLS configuration if more advanced configuration is needed.)
@@ -158,20 +154,18 @@ See `<<nng_tls_config_own_cert.3tls#,nng_tls_config_own_cert()>>` for more
 information.
 
 ((`NNG_OPT_TLS_AUTH_MODE`))::
-
-(`int`) This is a write-only option used to configure the authentication mode
-used.
-It can take an integer with value `NNG_TLS_AUTH_MODE_NONE`,
-`NNG_TLS_AUTH_MODE_REQUIRED`, or `NNG_TLS_AUTH_MODE_OPTIONAL`.
-See `<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>` for more
-details.
+(`int`) Write-only option used to configure the authentication mode used.
+Must be one of
+`NNG_TLS_AUTH_MODE_NONE`,
+`NNG_TLS_AUTH_MODE_REQUIRED`, or
+`NNG_TLS_AUTH_MODE_OPTIONAL`.
+See `<<nng_tls_config_auth_mode.3tls#,nng_tls_config_auth_mode()>>` for
+more details.
 
 `NNG_OPT_TLS_VERIFIED`::
-
-(bool) This is a read-only option that is `true` if the remote peer has been
-properly verified using TLS authentication, or `false` otherwise.
-This option may return incorrect
-results if peer authentication is disabled with `NNG_TLS_AUTH_MODE_NONE`.
+(`bool`) Whether the remote peer has been properly verified using TLS
+authentication.
+May return incorrect results if peer authentication is disabled.
 
 // We should also look at a hook mechanism for listeners. Probably this could
 // look like NNG_OPT_WS_LISTEN_HOOK_FUNC which would take a function pointer
diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc
index 5b7224a6..e7a9f108 100644
--- a/docs/man/nng_zerotier.7.adoc
+++ b/docs/man/nng_zerotier.7.adoc
@@ -138,7 +138,7 @@ The network is most likely not available.
 The following transport options are available:
 
 ((`NNG_OPT_ZT_HOME`))::
-  This is a string representing the "`home directory`", where the transport
+  (string) This option represents the "`home directory`", where the transport
   can store (and reuse) persistent state, such as key materials, node
   identity, and federation membership.
   This option must be set before the ZeroTier transport is first used.
@@ -152,38 +152,34 @@ It is perfectly valid for an application to have multiple node identities
 in this fashion.
 
 ((`NNG_OPT_ZT_NWID`))::
-  This is a read-only option for listeners, dialers, and pipes, and
-  provides a `uint64_t` in native byte order representing the 64-bit ZeroTier
-  network number.
+  (`uint64_t`) The 64-bit ZeroTier network number (native byte order).
 
 [[NNG_OPT_ZT_NODE]]
 ((`NNG_OPT_ZT_NODE`))::
-  This is a read-only option for listeners, dialers, and pipes, and
-  provides a `uint64_t` in native byte order representing the ZeroTier
-  40-bit node address.
+  (`uint64_t`) The ZeroTier  40-bit node address (native byte order).
 
 [[NNG_OPT_ZT_NETWORK_STATUS]]
 ((`NNG_OPT_ZT_NETWORK_STATUS`))::
   (((status, zerotier network)))
-  This is a read-only integer, representing the ZeroTier network status.
+  (`int`) The ZeroTier network status.
   See <<Network Status>> for an explanation of this option.
 
 [[NNG_OPT_ZT_NETWORK_NAME]]
 ((`NNG_OPT_ZT_NETWORK_NAME`))::
   (((name, zerotier network)))
-  This is a read-only ASCIIZ string containing the name of the network
+  (string) The name of the network
   as established by the ZeroTier network administrator.
 
 [[NNG_OPT_ZT_CONN_TIME]]
 ((`NNG_OPT_ZT_CONN_TIME`))::
-  The time to wait between sending connection attempts.
-  This is an `<<nng_duration.5#,nng_duration>>` (msec),
-  and is only used with dialers.
+  (`<<nng_duration.5#,nng_duration>>`)
+  The time to wait between sending connection attempts,
+  only used with dialers.
   The default is 500 msec.
 
 [[NNG_OPT_ZT_CONN_TRIES]]
 ((`NNG_OPT_ZT_CONN_TRIES`))::
-  The maximum number (`int`) of attempts to try to establish a connection
+  (`int`) The maximum number of attempts to try to establish a connection
   before reporting a timeout, and is only used with dialers.
   The default is 240, which results in a 2 minute timeout if
   `NNG_OPT_ZT_CONN_TIME` is at its default of 500.
@@ -191,36 +187,35 @@ in this fashion.
 
 [[NNG_OPT_ZT_PING_TIME]]
 ((`NNG_OPT_ZT_PING_TIME`))::
-  If no traffic has been received from the ZeroTier peer after this
+  (`<<nng_duration.5#,nng_duration>>`) If no traffic has been received from
+  the ZeroTier peer after this
   period of time, then a "`ping`" message is sent to check if the peer
-  is still alive.  This is an `<<nng_duration.5#,nng_duration>>` (msec).
+  is still alive.
 
 [[NNG_OPT_ZT_PING_TRIES]]
 ((`NNG_OPT_ZT_PING_TRIES`))::
-  If this number (`int`) of consecutive "`ping`" requests are sent to the
+  (`int`) If this number of consecutive "`ping`" requests are sent to the
   peer with no response (and no other intervening traffic), then the
-  peer is assumed to be dead and the connection is closed.  Note that
-  if any traffic is received from the peer, then the underlying counter
-  is reset to zero.
+  peer is assumed to be dead and the connection is closed.
 
 [[NNG_OPT_ZT_MTU]]
 ((`NNG_OPT_ZT_MTU`))::
-  This is a read-only size (`size_t`) representing the ZeroTier virtual
-  network MTU; this is the Virtual Layer 2 MTU.  The headers used by
+  (`size_t`) The ZeroTier virtual network MTU (read-only) as configured
+  on the network; this is the Virtual Layer 2 MTU.  The headers used by
   this transport and the protocols consume some of this for each message
   sent over the network.  (The transport uses 20-bytes of this, and each
   protocol may consume additional space, typically not more than 16-bytes.)
 
 [[NNG_OPT_ZT_ORBIT]]
-((`NNG_OPT_ZT_ORBIT`))(((orbit, ZeroTier)))(((federation,ZeroTier))):
-  This is a write-only option that takes an array of two `uint64_t` values,
+((`NNG_OPT_ZT_ORBIT`))(((orbit, ZeroTier)))(((federation,ZeroTier)))::
+  (`uint64_t[2]`) Write-only array of two `uint64_t` values,
   indicating the ID of a ZeroTier "`moon`", and the node ID of the root server
   for that moon.  (The ID may be zero if the moon ID is the same as its
   root server ID, which is conventional.)
 
 [[NNG_OPT_ZT_DEORBIT]]
 ((`NNG_OPT_ZT_DEORBIT`))::
-  This write-only option takes a single `uint64_t` indicating the moon
+  (`uint64_t`) Write-only option indicating the moon
   ID to "`deorbit`".  If the node is not already orbiting the moon, then
   this has no effect.