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, 73 insertions, 0 deletions

diff --git a/docs/man/nng_tls_dialer_getopt.3tls.adoc b/docs/man/nng_tls_dialer_getopt.3tls.adoc
new file mode 100644
index 00000000..6790092f
--- /dev/null
+++ b/docs/man/nng_tls_dialer_getopt.3tls.adoc
@@ -0,0 +1,73 @@
+= nng_tls_dialer_getopt(3tls)
+//
+// Copyright 2018 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_tls_dialer_getopt - get option from TLS dialer
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tls/tls.h>
+
+int nng_tls_getopt(nng_tls_dialer *d, const char *name, void *data, size_t *sizep);
+----
+
+== DESCRIPTION
+
+The `nng_tls_dialer_getopt()` is used to retrieve the value of the option _name_
+for the <<nng_tls_dialer.5#,TLS dialer>> _d_.
+The size of the buffer located at _data_ to receive the copy is passed by the
+caller at the location referenced by _sizep_.
+If this size is sufficient to hold the entire object, the object is copied into
+the buffer specified by _data_.
+In either event, the size of the source object (the amount of data copied,
+or that would have been copied if sufficient space were available) is stored
+at the location of _sizep_.
+
+=== Options
+
+The options specifically suppported for retrieval from TLS dialers are:
+
+* <<nng_options.5#NNG_OPT_LOCADDR,`NNG_OPT_LOCADDR`>>
+* <<nng_tcp_options.5#NNG_OPT_TCP_KEEPALIVE,`NNG_OPT_TCP_KEEPALIVE`>>
+* <<nng_tcp_options.5#NNG_OPT_TCP_NODELAY,`NNG_OPT_TCP_NODELAY`>>
+* <<nng_tls_options.5#NNG_OPT_TLS_CONFIG,`NNG_OPT_TLS_CONFIG`>>
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+[horizontal]
+`NNG_ECLOSED`:: The dialer is closed.
+`NNG_EINVAL`:: There was insufficient space to receive the object.
+	The amount of data actually needed is returned in _sizep_.
+`NNG_ENOTSUP`:: The option _name_ is not supported.
+`NNG_EWRITEONLY`:: The option _name_ may not read.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tls_dialer_setopt.3tls#,nng_tls_dialer_setopt(3tls)>>,
+<<nng_tls_getopt.3tls#,nng_tls_getopt(3tls)>>,
+<<nng_options.5#,nng_options(5)>>,
+<<nng_tcp_options.5#,nng_tcp_options(5)>>,
+<<nng_tls.5#,nng_tls(5)>>,
+<<nng_tls_config.5#,nng_tls_config(5)>>,
+<<nng_tls_dialer.5#,nng_tls_dialer(5)>>,
+<<nng_tls_options.5#,nng_tls_options(5)>>
+