add documentation

2 files changed, 22 insertions, 10 deletions

diff --git a/src/lib/tls/asio/asio_stream.h b/src/lib/tls/asio/asio_stream.h
index 1cd2af87b..34b9635a9 100644
--- a/src/lib/tls/asio/asio_stream.h
+++ b/src/lib/tls/asio/asio_stream.h
@@ -202,6 +202,12 @@ class Stream final : public StreamBase<Channel>
       //
       // -- -- asio::ssl::stream compatibility methods
       //
+      //       The OpenSSL-based stream contains an operation flag that tells
+      //       the stream to either impersonate a TLS server or client. This
+      //       implementation defines those modes at compile time (via template
+      //       specialization of the StreamBase class) and merely checks the
+      //       flag's consistency before performing the respective handshakes.
+      //
 
       void handshake(handshake_type type)
          {
@@ -217,6 +223,15 @@ class Stream final : public StreamBase<Channel>
             }
          }
 
+      template <typename HandshakeHandler>
+      BOOST_ASIO_INITFN_RESULT_TYPE(HandshakeHandler,
+                                    void(boost::system::error_code))
+      async_handshake(handshake_type type, HandshakeHandler&& handler)
+         {
+         validate_handshake_type(type);
+         return async_handshake(handler);
+         }
+
       template<typename ConstBufferSequence>
       void handshake(handshake_type type, const ConstBufferSequence& buffers)
          {
@@ -237,15 +252,6 @@ class Stream final : public StreamBase<Channel>
             }
          }
 
-      template <typename HandshakeHandler>
-      BOOST_ASIO_INITFN_RESULT_TYPE(HandshakeHandler,
-                                    void(boost::system::error_code))
-      async_handshake(handshake_type type, HandshakeHandler&& handler)
-         {
-         validate_handshake_type(type);
-         return async_handshake(handler);
-         }
-
       template <typename ConstBufferSequence, typename BufferedHandshakeHandler>
       BOOST_ASIO_INITFN_RESULT_TYPE(BufferedHandshakeHandler,
                                     void(boost::system::error_code, std::size_t))
diff --git a/src/lib/tls/asio/asio_stream_base.h b/src/lib/tls/asio/asio_stream_base.h
index 161392ad8..7d41215c6 100644
--- a/src/lib/tls/asio/asio_stream_base.h
+++ b/src/lib/tls/asio/asio_stream_base.h
@@ -25,9 +25,13 @@ enum handshake_type
    };
 
 
-/* Base class for all Botan::TLS::Stream implementations.
+/** \brief Base class for all Botan::TLS::Stream implementations.
  *
+ * This template must be specialized for all the Botan::TLS::Channel to be used.
+ * Currently it only supports the Botan::TLS::Client channel that impersonates
+ * the client-side of a TLS connection.
  *
+ * TODO: create a Botan::TLS::Server specialization
  */
 template <class Channel>
 class StreamBase
@@ -58,6 +62,7 @@ class StreamBase<Botan::TLS::Client>
       using handshake_type = Botan::TLS::handshake_type;
 
    protected:
+      //! \brief validate the OpenSSL compatibility enum `handshake_type`
       void validate_handshake_type(handshake_type type)
          {
          if(type != handshake_type::client)
@@ -66,6 +71,7 @@ class StreamBase<Botan::TLS::Client>
             }
          }
 
+      //! \brief validate the OpenSSL compatibility enum `handshake_type`
       bool validate_handshake_type(handshake_type type, boost::system::error_code& ec)
          {
          if(type != handshake_type::client)