code comments

3 files changed, 7 insertions, 5 deletions

diff --git a/src/lib/tls/asio/asio_async_base.h b/src/lib/tls/asio/asio_async_base.h
index af9199288..e8bc03fee 100644
--- a/src/lib/tls/asio/asio_async_base.h
+++ b/src/lib/tls/asio/asio_async_base.h
@@ -46,6 +46,7 @@ struct AsyncBase
          {
          if(!isContinuation)
             {
+            // \note(toesterreich): Is this ok to do with bind_handler? Do we need placeholders?
             boost::asio::post(boost::asio::bind_executor(
                                  m_work.get_executor(), boost::beast::bind_handler(std::move(m_handler), args...))
                              );
diff --git a/src/lib/tls/asio/asio_async_handshake_op.h b/src/lib/tls/asio/asio_async_handshake_op.h
index 1a93ab78b..18e368603 100644
--- a/src/lib/tls/asio/asio_async_handshake_op.h
+++ b/src/lib/tls/asio/asio_async_handshake_op.h
@@ -60,11 +60,10 @@ struct AsyncHandshakeOperation : public AsyncBase<Handler, typename Stream::exec
          // send tls packets
          if(m_core.hasDataToSend())
             {
-            // TODO comment: plainBytesTransferred is 0 here because...  we construct a write operation to use it only
-            // as a handler for our async_write call, not for actually calling it.  However, once
-            // AsyncWriteOperation::operator() is called as the handler, it will consume the send buffer and call (this)
-            // as it's own handler. Now we know that AsyncHandshakeOperation::operator() checks bytesTransferred first.
-            // We want it to NOT receive data into the channel, hence we set plainBytesTransferred to 0 here.
+            // \note: we construct `AsyncWriteOperation` with 0 as its last parameter (`plainBytesTransferred`).
+            //        This operation will eventually call `*this` as its own handler, passing the 0 back to this call
+            //        operator. This is necessary because, the check of `bytesTransferred > 0` assumes that
+            //        `bytesTransferred` bytes were just read and are in the cores input_buffer for further processing.
             AsyncWriteOperation<
             AsyncHandshakeOperation<typename std::decay<Handler>::type, Stream, Allocator>,
                                     Stream,
diff --git a/src/lib/tls/asio/asio_async_write_op.h b/src/lib/tls/asio/asio_async_write_op.h
index 4103987ae..67cc2cd5b 100644
--- a/src/lib/tls/asio/asio_async_write_op.h
+++ b/src/lib/tls/asio/asio_async_write_op.h
@@ -42,6 +42,8 @@ struct AsyncWriteOperation : public AsyncBase<Handler, typename Stream::executor
    void operator()(boost::system::error_code ec, std::size_t bytes_transferred, bool isContinuation = true)
       {
       m_core.consumeSendBuffer(bytes_transferred);
+      // the size of the sent TLS record can differ from the size of the payload due to TLS encryption. We need to tell
+      // the handler how many bytes of the original data we already processed.
       this->invoke(isContinuation, ec, ec ? 0 : m_plainBytesTransferred);
       }