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

diff --git a/docs/man/nng_tls_dialer_dial.3tls.adoc b/docs/man/nng_tls_dialer_dial.3tls.adoc
new file mode 100644
index 00000000..31d9036d
--- /dev/null
+++ b/docs/man/nng_tls_dialer_dial.3tls.adoc
@@ -0,0 +1,65 @@
+= nng_tls_dialer_dial(3tls)
+//
+// 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_tls_dialer_dial - initiate outgoing TLS connection
+
+== SYNOPSIS
+
+[source, c]
+----
+#include <nng/nng.h>
+#include <nng/supplemental/tls/tls.h>
+
+void nng_tls_dialer_dial(nng_tls_dialer *d, const nng_sockaddr *sa, nng_aio *aio);
+----
+
+== DESCRIPTION
+
+The `nng_tls_dialer_dial()` attempts to establish a TLS connection to the
+remote peer identified by _sa_, using the dialer _d_.
+The operation is completed asynchronously, using _aio_.
+
+The address _sa_ must be in the `NNG_AF_INET` or `NNG_AF_INET6` families,
+and have a valid IPv4 or IPv6 address and TCP port number.
+
+If a connection is successfully established, the _aio_ will have the
+resulting <<nng_tls.5#,`nng_tls`>> stored as its first output.
+(See <<nng_aio_get_output.3#,`nng_aio_get_output()`>>.)
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+[horizontal]
+`NNG_EADDRINVAL`:: The address specified is invalid.
+`NNG_ECANCELED`:: The operation was aborted.
+`NNG_ECLOSED`:: The dialer is closed.
+`NNG_ECONNREFUSED`:: The connection was refused by the server.
+`NNG_ECONNRESET`:: The connection was reset by the server.
+`NNG_ECRYPTO`:: Cryptographic or certificate validation error.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+
+== SEE ALSO
+
+[.text-left]
+<<nng_strerror.3#,nng_strerror(3)>>,
+<<nng_tls_dialer_alloc.3tls#,nng_tls_dialer_alloc(3tls)>>,
+<<nng_tls_dialer_close.3tls#,nng_tls_dialer_close(3tls)>>,
+<<nng_tls_dialer_free.3tls#,nng_tls_dialer_free(3tls)>>,
+<<nng_aio.5#,nng_aio(5)>>,
+<<nng_sockaddr.5#,nng_sockaddr(5)>>,
+<<nng_tls.5#,nng_tls(5)>>,
+<<nng_tls_dialer.5#,nng_tls_dialer(5)>>