[glib-networking/mcatanzaro/base-rebase: 25/45] gtlsconnection-base: improve comments

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 809c617a145e11a923bf104c0b5ce158c5a81e3e
Author: Michael Catanzaro <mcatanzaro igalia com>
Date:   Sun Apr 7 16:03:41 2019 -0500

    gtlsconnection-base: improve comments
    
    Port of 6e84378392696c8780addfc8b9c958cb6917a81a and 40285bf52105c782730dff2e85d7c21efefa150a

 tls/base/gtlsconnection-base.c | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)
---
diff --git a/tls/base/gtlsconnection-base.c b/tls/base/gtlsconnection-base.c
index f06c7bc..79ffbfd 100644
--- a/tls/base/gtlsconnection-base.c
+++ b/tls/base/gtlsconnection-base.c
@@ -55,22 +55,30 @@
 
 typedef struct
 {
-  /* When operating in stream mode.
-   * Mutually exclusive with base_socket.
+  /* When operating in stream mode, as a GTlsConnection. These are
+   * mutually-exclusive with base_socket. There are two different
+   * GIOStreams here: (a) base_io_stream and (b) the GTlsConnection
+   * itself. base_io_stream is the GIOStream used to create the GTlsConnection,
+   * and corresponds to the GTlsConnection::base-io-stream property.
+   * base_istream and base_ostream are the GInputStream and GOutputStream,
+   * respectively, of base_io_stream. These are for the underlying sockets that
+   * don't know about TLS.
+   *
+   * Then the GTlsConnection also has tls_istream and tls_ostream, which
+   * wrap the aforementioned base streams with a TLS session.
+   *
+   * When operating in datagram mode, none of these are used.
    */
   GIOStream             *base_io_stream;
   GPollableInputStream  *base_istream;
   GPollableOutputStream *base_ostream;
-
-  /* When operating in stream mode; when operating in datagram mode, the
-   * GTlsConnectionBase itself is the DTLS GDatagramBased (and uses
-   * base_socket for its underlying I/O):
-   */
   GInputStream          *tls_istream;
   GOutputStream         *tls_ostream;
 
-  /* When operating in datagram mode.
-   * Mutually exclusive with base_io_stream.
+  /* When operating in datagram mode, as a GDtlsConnection, the
+   * GTlsConnection is itself the DTLS GDatagramBased. It uses base_socket
+   * for the underlying I/O. It is mutually-exclusive with base_io_stream and
+   * the other streams.
    */
   GDatagramBased        *base_socket;