fixes #1071 tran_chkopt can be cleaned up

This is a sweeping cleanup of the transport logic around options,
and also harmonizes the names used when setting or getting options.
Additionally, legacy methods are now moved into a separate file and
can be elided via CMake or a preprocessor define.

Fundamentally, the ability to set to transport options via the socket
is deprecated; there are numerous problems with this and my earlier
approaches to deal with this have been somewhat misguided.  Further
these approaches will not work with future protocol work that is
planned (were some options need to be negotiated with peers at the
time of connection establishment.)

Documentation has been updated to reflect this.  The test suites still
make rather broad use of the older APIs, and will be converted later.

1 files changed, 8 insertions, 4 deletions

diff --git a/docs/man/nng_socket_set.3.adoc b/docs/man/nng_socket_set.3.adoc
index 0b6df4f9..aa5784f3 100644
--- a/docs/man/nng_socket_set.3.adoc
+++ b/docs/man/nng_socket_set.3.adoc
@@ -1,6 +1,6 @@
 = nng_socket_set(3)
 //
-// Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -45,13 +45,17 @@ The actual options that may be configured in this way vary, and are
 specified by _opt_.
 A number of them are documented in xref:nng_options.5.adoc[nng_options(5)].
 
-Additionally some transport-specific and protocol-specific options are
-documented with the transports and protocols themselves.
+Protocol-specific options are documented with the protocol in question.
+
+IMPORTANT: Access to transport options via this function is deprecated, and may be
+removed from a future release.  Applications should instead make use of
+xref:nng_dialer_set.3.adoc[nng_dialer_get] or
+xref:nng_listener_set.3.adoc[nng_listener_get] for specific dialers or listeners.
 
 === Forms
 
 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.
+on the actual option, and is documented with the option itself.
 
 `nng_socket_set()`::
 This function is untyped, and can be used to configure any arbitrary data.