fixes #858 Document the TLS public API

This also includes a number of the documentation improvements.
The options document has been broken up into separate pages for
each of the transport specific options.  We have made various
other minor improvements, fixes to markup, and cross-references.

1 files changed, 110 insertions, 0 deletions

diff --git a/docs/man/nng_tcp_options.5.adoc b/docs/man/nng_tcp_options.5.adoc
new file mode 100644
index 00000000..f16af5ea
--- /dev/null
+++ b/docs/man/nng_tcp_options.5.adoc
@@ -0,0 +1,110 @@
+= nng_tcp_options(5)
+//
+// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2019 Devolutions <info@devolutions.net>
+//
+// This document is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+== NAME
+
+nng_tcp_options - TTCP-specific options
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+
+
+#define NNG_OPT_TCP_NODELAY   "tcp-nodelay"
+#define NNG_OPT_TCP_KEEPALIVE "tcp-keepalive"
+----
+
+== DESCRIPTION
+
+This page documents the various standard options that can be set or
+retrieved on objects using TCP in the _nng_ library.
+
+The option names should always be used by their symbolic definitions.
+
+In the following list of options, the name of the option is supplied,
+along with the data type of the underlying value.
+
+Some options are only meaningful or supported in certain contexts, or may
+have other access restrictions.
+An attempt has been made to include details about such restrictions in the
+description of the option.
+
+The following options are generally application to objects making use of
+TCP/IP communications.
+
+=== TCP Options
+
+[[NNG_OPT_TCP_NODELAY]]
+((`NNG_OPT_TCP_NODELAY`))::
+(`bool`)
+This option is used to disable (or enable) the use of ((Nagle's algorithm))
+for TCP connections.
++
+NOTE: This setting may apply to transports that are built on top of TCP.
+See the transport documentation for each transport for details.
++
+When `true` (the default), messages are sent immediately by the underlying
+TCP stream without waiting to gather more data.
++
+When `false`, Nagle's algorithm is enabled, and the TCP stream may
+wait briefly in attempt to coalesce messages.
+Nagle's algorithm is useful on low-bandwidth connections to reduce overhead,
+but it comes at a cost to latency.
++
+When used on a dialer or a listener, the value affects how newly
+created connections will be configured.
+
+[[NNG_OPT_TCP_KEEPALIVE]]
+((`NNG_OPT_TCP_KEEPALIVE`))::
+(`bool`)
+This option is used to enable the sending of keep-alive messages on
+the underlying TCP stream.
+This option is `false` by default.
++
+NOTE: This setting may apply to transports that are built on top of TCP.
+See the transport documentation for each transport for details.
++
+When enabled, if no messages are seen for a period of time, then
+a zero length TCP message is sent with the ACK flag set in an attempt
+to tickle some traffic from the peer.
+If none is still seen (after some platform-specific number of retries and
+timeouts), then the remote peer is presumed dead, and the connection is closed.
++
+When used on a dialer or a listener, the value affects how newly
+created connections will be configured.
++
+TIP: This option has two purposes.
+First, it can be used to detect dead peers on an otherwise quiescent network.
+Second, it can be used to keep connection table entries in NAT and other
+middleware from being expiring due to lack of activity.
+
+=== Inherited Options
+
+Generally, the following option values are also available for TCP objects,
+when appropriate for the context:
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_options.5#NNG_OPT_REMADDR,`NNG_OPT_REMADDR`>>
+
+== SEE ALSO
+
+[.text-left]
+<<nng_tcp_dialer_getopt.3tcp#,nng_tcp_dialer_getopt(3tcp)>>,
+<<nng_tcp_dialer_setopt.3tcp#,nng_tcp_dialer_setopt(3tcp)>>,
+<<nng_tcp_getopt.3tcp#,nng_tcp_getopt(3tcp)>>,
+<<nng_tcp_listener_getopt.3tcp#,nng_tcp_listener_getopt(3tcp)>>,
+<<nng_tcp_listener_setopt.3tcp#,nng_tcp_listener_setopt(3tcp)>>,
+<<nng_tcp_setopt.3tcp#,nng_tcp_setopt(3tcp)>>,
+<<nng_options.5#,nng_options(5)>>
+<<nng.7#,nng(7)>>