sqlx-postgres: Add comments

Author: joeydewaal

sqlx-postgres/src/connection/establish.rs

@@ -12,7 +12,10 @@ use super::worker::{Shared, Worker};
 
 impl PgConnection {
     pub(crate) async fn establish(options: &PgConnectOptions) -> Result<Self, Error> {
+        // A channel to communicate postgres notifications between the bg worker and a `PgListener`.
         let (notif_tx, notif_rx) = unbounded();
+
+        // Shared state between the bg worker and the `PgConnection`
         let shared = Shared::new();
 
         // Upgrade to TLS if we were asked to and the server supports it
@@ -116,7 +119,7 @@ impl PgConnection {
                 }
 
                 BackendMessageFormat::ReadyForQuery => {
-                    // Transaction status is updated in the bg worker.
+                    // The transaction status is updated in the bg worker.
                     break;
                 }
 

sqlx-postgres/src/connection/mod.rs

@@ -40,6 +40,7 @@ pub struct PgConnection {
 }
 
 pub struct PgConnectionInner {
+    // channel to the background worker
     chan: UnboundedSender<IoRequest>,
 
     pub(crate) notifications: UnboundedReceiver<Notification>,

sqlx-postgres/src/connection/pipe.rs

@@ -7,6 +7,8 @@ use crate::{
     PgDatabaseError,
 };
 
+/// A temporary stream of responses sent from the background worker. The steam is stopped when
+/// either a [ReadyForQuery] of [CopyInResponse] is received.
 pub struct Pipe {
     receiver: UnboundedReceiver<ReceivedMessage>,
 }
@@ -21,6 +23,7 @@ impl Pipe {
     }
 
     pub async fn recv_ready_for_query(&mut self) -> Result<(), Error> {
+        // The transaction status is updated in the bg worker.
         let _: ReadyForQuery = self.recv_expect().await?;
         Ok(())
     }
@@ -30,7 +33,7 @@ impl Pipe {
             let message = self.recv().await?;
 
             if let BackendMessageFormat::ReadyForQuery = message.format {
-                let _: ReadyForQuery = message.decode()?;
+                // The transaction status is updated in the bg worker.
                 break;
             }
         }

sqlx-postgres/src/connection/request.rs

@@ -10,6 +10,7 @@ pub struct IoRequest {
     pub data: Vec<u8>,
 }
 
+/// A buffer that contains encoded postgres messages, ready to be sent over the wire.
 pub struct MessageBuf {
     data: Vec<u8>,
 }