Apply comment suggestions from code review

Co-Authored-By: hrantzsch <[email protected]>

4 files changed, 8 insertions, 5 deletions

diff --git a/src/lib/tls/asio/asio_async_handshake_op.h b/src/lib/tls/asio/asio_async_handshake_op.h
index f94a14ce3..c23e654ff 100644
--- a/src/lib/tls/asio/asio_async_handshake_op.h
+++ b/src/lib/tls/asio/asio_async_handshake_op.h
@@ -59,7 +59,7 @@ struct AsyncHandshakeOperation : public AsyncBase<Handler, typename Stream::exec
          {
          reenter(this)
             {
-            // Provide TLS data from the core to the TLS::Channel
+            // Provide encrypted TLS data received from the network to TLS::Channel for decryption
             if(bytesTransferred > 0 && !ec)
                {
                boost::asio::const_buffer read_buffer {m_core.input_buffer.data(), bytesTransferred};
@@ -73,7 +73,7 @@ struct AsyncHandshakeOperation : public AsyncBase<Handler, typename Stream::exec
                   }
                }
 
-            // Write TLS data that TLS::Channel has provided to the core
+            // Write encrypted TLS data provided by the TLS::Channel on the wire
             if(m_core.hasDataToSend() && !ec)
                {
                // Note: we construct `AsyncWriteOperation` with 0 as its last parameter (`plainBytesTransferred`).
@@ -88,7 +88,7 @@ struct AsyncHandshakeOperation : public AsyncBase<Handler, typename Stream::exec
                return;
                }
 
-            // Read more data from the socket
+            // Read more encrypted TLS data from the network
             if(!m_stream.native_handle()->is_active() && !ec)
                {
                m_stream.next_layer().async_read_some(m_core.input_buffer, std::move(*this));
diff --git a/src/lib/tls/asio/asio_async_read_op.h b/src/lib/tls/asio/asio_async_read_op.h
index 6803019ad..dc963d786 100644
--- a/src/lib/tls/asio/asio_async_read_op.h
+++ b/src/lib/tls/asio/asio_async_read_op.h
@@ -64,7 +64,7 @@ struct AsyncReadOperation : public AsyncBase<Handler, typename Stream::executor_
             {
             if(bytes_transferred > 0 && !ec)
                {
-               // We have transferred encrypted data from the socket, now hand it to the channel.
+               // We have received encrypted data from the network, now hand it to TLS::Channel for decryption.
                boost::asio::const_buffer read_buffer{m_core.input_buffer.data(), bytes_transferred};
                try
                   {
diff --git a/src/lib/tls/asio/asio_async_write_op.h b/src/lib/tls/asio/asio_async_write_op.h
index 97f5cbbc7..cec145ebe 100644
--- a/src/lib/tls/asio/asio_async_write_op.h
+++ b/src/lib/tls/asio/asio_async_write_op.h
@@ -63,6 +63,8 @@ struct AsyncWriteOperation : public AsyncBase<Handler, typename Stream::executor
          {
          reenter(this)
             {
+            // mark the number of encrypted bytes sent to the network as "consumed"
+            // Note: bytes_transferred will be zero on first call
             m_core.consumeSendBuffer(bytes_transferred);
 
             if(m_core.hasDataToSend() && !ec)
diff --git a/src/lib/tls/asio/asio_stream.h b/src/lib/tls/asio/asio_stream.h
index 46c1e37a6..6d69d5392 100644
--- a/src/lib/tls/asio/asio_stream.h
+++ b/src/lib/tls/asio/asio_stream.h
@@ -549,7 +549,8 @@ class Stream : public StreamBase<Channel>
          {
          std::size_t sent = 0;
          // NOTE: This is not asynchronous: it encrypts the data synchronously.
-         // Only writing to the socket is asynchronous.
+         // The data encrypted by native_handle()->send() is synchronously stored in the send_buffer of m_core,
+         // but is not actually written to the wire, yet.
          for(auto it = boost::asio::buffer_sequence_begin(buffers);
                it != boost::asio::buffer_sequence_end(buffers);
                it++)