docs: data messages documentation

proto/src/handshake/request.rs

@@ -9,8 +9,8 @@ pub struct HandshakeRequest {
 
 impl HandshakeRequest {
 
-    /// Creates a new `HandshakeRequest` with the specified version.
+    /// Creates a new `HandshakeRequest` with the specified protocol version.
-    /// Expected `version` is 196608 (3.0).
+    /// Expected `version` is `196608` for the 3.0.
     pub fn new(version: i32) -> Self {
         Self {
             version,

proto/src/lib.rs

@@ -1,5 +1,5 @@
-//! # PostgreSQL 16 Protocol
+//! # PostgreSQL Protocol
-//! Low-level PostgreSQL protocol implementation for the version 16, protocol version 3.0.
+//! Low-level PostgreSQL protocol implementation for the server version 16, protocol version 3.0.
 //! Includes server and client side handshake with no password authentication.
 
 pub mod handshake;

proto/src/message/backend.rs

@@ -5,6 +5,8 @@ use crate::message::primitive::pgstring::PgString;
 use crate::message::proto_message::ProtoMessage;
 use bincode::{Decode, Encode};
 
+/// Backend messages sent from the server to the client.
+/// For more info visit the [`55.2.3. Message Formats`](https://www.postgresql.org/docs/current/protocol-message-formats.html)
 #[derive(Debug)]
 pub enum BackendMessage {
     AuthenticationOk(AuthenticationOkData),

proto/src/message/frontend.rs

@@ -4,6 +4,8 @@ use crate::message::primitive::pgstring::PgString;
 use crate::message::proto_message::ProtoMessage;
 use bincode::{Decode, Encode};
 
+/// Frontend messages sent from the client to the server.
+/// For more info visit the [`55.2.3. Message Formats`](https://www.postgresql.org/docs/current/protocol-message-formats.html)
 #[derive(Debug)]
 pub enum FrontendMessage {
     Query(QueryData),

proto/src/message/primitive/config.rs

@@ -1,7 +0,0 @@
-use bincode::config::{BigEndian, Configuration, Fixint};
-
-pub fn pg_proto_config() -> Configuration<BigEndian, Fixint> {
-    bincode::config::standard()
-        .with_big_endian()
-        .with_fixed_int_encoding()
-}

proto/src/message/primitive/data.rs

@@ -1,6 +1,12 @@
 use crate::message::errors::{ProtoDeserializeError, ProtoSerializeError};
-use crate::message::primitive::config::pg_proto_config;
 use bincode::{Decode, Encode};
+use bincode::config::{BigEndian, Configuration, Fixint};
+
+fn pg_proto_config() -> Configuration<BigEndian, Fixint> {
+    bincode::config::standard()
+        .with_big_endian()
+        .with_fixed_int_encoding()
+}
 
 pub trait MessageData: Sized {
     fn serialize(&self) -> Result<Vec<u8>, ProtoSerializeError>;

proto/src/message/primitive/mod.rs

@@ -1,4 +1,3 @@
-pub(crate) mod config;
 pub(crate) mod data;
 pub mod pglist;
 pub mod pgstring;

proto/src/message/primitive/pglist.rs

@@ -4,6 +4,9 @@ use bincode::error::{DecodeError, EncodeError};
 use bincode::{BorrowDecode, Decode, Encode};
 use std::marker::PhantomData;
 
+/// Item list common in PostgreSQL messages.
+/// - Generic type `T` is the type of the items in the list.
+/// - Generic type `U` is the type of the list length (`i16` or `i32`).
 #[derive(Debug, Clone, PartialEq, BorrowDecode)]
 pub struct PgList<T, U>(Vec<T>, PhantomData<U>);
 

proto/src/message/primitive/pgstring.rs

@@ -4,6 +4,7 @@ use bincode::enc::Encoder;
 use bincode::error::{DecodeError, EncodeError};
 use bincode::{BorrowDecode, Decode, Encode};
 
+/// PostgreSQL format of string encoded as a null-terminated string.
 #[derive(Debug, Clone, BorrowDecode)]
 pub struct PgString(String);
 

proto/src/message/special.rs

@@ -4,10 +4,15 @@ use bincode::enc::Encoder;
 use bincode::error::{DecodeError, EncodeError};
 use bincode::{Decode, Encode};
 
+/// Special messages sent during handshake or to cancel request.
+/// Sent in different format to preserve compatibility with older protocol versions.
 #[derive(Debug)]
 pub enum SpecialMessage {
+    /// Sent by client to cancel request.
     CancelRequest(CancelRequestData),
+    /// Sent by client to request upgrade to SSL connection.
     SSLRequest,
+    /// Sent by client to initiate the handshake.
     StartupMessage(StartupMessageData),
 }