Add various bits of documentation

src/pg/protocol/mod.rs

@@ -1,3 +1,6 @@
+//! Low level PostgreSQL protocol. Defines the encoding and decoding of the messages communicated 
+//! to and from the database server.
+
 mod bind;
 mod cancel_request;
 mod close;

src/pg/types/boolean.rs

@@ -1,4 +1,4 @@
-use super::{Pg, PgTypeMetadata};
+use super::{Pg, PgTypeMetadata, PgTypeFormat};
 use crate::{
     deserialize::FromSql,
     serialize::{IsNull, ToSql},
@@ -8,6 +8,7 @@ use crate::{
 impl HasSqlType<bool> for Pg {
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 16,
             array_oid: 1000,
         }

src/pg/types/character.rs

@@ -1,4 +1,4 @@
-use super::{Pg, PgTypeMetadata};
+use super::{Pg, PgTypeMetadata, PgTypeFormat};
 use crate::{
     deserialize::FromSql,
     serialize::{IsNull, ToSql},
@@ -10,6 +10,7 @@ impl HasSqlType<&'_ str> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 25,
             array_oid: 1009,
         }

src/pg/types/mod.rs

@@ -1,3 +1,32 @@
+//! PostgreSQL types.
+//!
+//! The following types are supported by this crate, 
+//! along with the corresponding Postgres types:
+//!
+//! ### Standard
+//!
+//! | Rust type                         | Postgres type(s)                     |
+//! |-----------------------------------|--------------------------------------|
+//! | `i16`                             | SMALLINT, SMALLSERIAL                |
+//! | `i32`                             | INT, SERIAL                          |
+//! | `i64`                             | BIGINT, BIGSERIAL                    |
+//! | `f32`                             | REAL                                 |
+//! | `f64`                             | DOUBLE PRECISION                     |
+//! | `&str`/`String`                   | VARCHAR, CHAR(n), TEXT, CITEXT, NAME |
+//! | `&[u8]`/`Vec<u8>`                 | BYTEA                                |
+//!
+//! ### PostgreSQL specific
+//!
+//! | Rust type                         | Postgres type(s)                     |
+//! |-----------------------------------|--------------------------------------|
+//! | `bool`                            | BOOL                                 |
+//! | `i8`                              | "char"                               |
+//! | `u32`                             | OID                                  |
+//! | `&[u8]`/`Vec<u8>`                 | BYTEA                                |
+//! | `HashMap<String, Option<String>>` | HSTORE                               |
+//! | `IpAddr`                          | INET                                 |
+//!
+
 use super::Pg;
 use crate::types::TypeMetadata;
 
@@ -5,7 +34,18 @@ mod boolean;
 mod character;
 mod numeric;
 
+pub enum PgTypeFormat {
+    Text = 0,
+    Binary = 1,
+}
+
+/// Provides the OIDs for a SQL type and the expected format to be used for 
+/// transmission between Rust and PostgreSQL.
+///
+/// While the BINARY format is preferred in most cases, there are scenarios 
+/// where only the TEXT format may be available for a type.
 pub struct PgTypeMetadata {
+    pub format: PgTypeFormat,
     pub oid: u32,
     pub array_oid: u32,
 }

src/pg/types/numeric.rs

@@ -1,4 +1,4 @@
-use super::{Pg, PgTypeMetadata};
+use super::{Pg, PgTypeMetadata, PgTypeFormat};
 use crate::{
     deserialize::FromSql,
     serialize::{IsNull, ToSql},
@@ -10,6 +10,7 @@ impl HasSqlType<i16> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 21,
             array_oid: 1005,
         }
@@ -36,6 +37,7 @@ impl HasSqlType<i32> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 23,
             array_oid: 1007,
         }
@@ -62,6 +64,7 @@ impl HasSqlType<i64> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 20,
             array_oid: 1016,
         }
@@ -88,6 +91,7 @@ impl HasSqlType<f32> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 700,
             array_oid: 1021,
         }
@@ -112,6 +116,7 @@ impl HasSqlType<f64> for Pg {
     #[inline]
     fn metadata() -> PgTypeMetadata {
         PgTypeMetadata {
+            format: PgTypeFormat::Binary,
             oid: 701,
             array_oid: 1022,
         }

src/query.rs

@@ -81,6 +81,7 @@ where
     }
 }
 
+/// Construct a full SQL query using raw SQL.
 #[inline]
 pub fn query<'q, DB>(query: &'q str) -> SqlQuery<'q, DB>
 where

src/serialize.rs

@@ -1,3 +1,4 @@
+//! Types and traits related to serializing values for the database.
 use crate::{backend::Backend, types::HasSqlType};
 
 /// Annotates the result of [ToSql] to differentiate between an empty value and a null value.
@@ -12,10 +13,21 @@ pub enum IsNull {
 }
 
 /// Serializes a single value to be sent to the database.
+///
+/// The data must be written to the buffer in the expected format for the given backend.
+///
+/// When possible, implementations of this trait should prefer using an existing implementation, 
+/// rather than writing to `out` directly.
 pub trait ToSql<DB: Backend> {
+    /// Writes the value of `self` into `buf` as the expected format for the given backend.
+    ///
+    /// The return value indicates if this value should be represented as `NULL`. 
+    /// If this is the case, implementations **must not** write anything to `out`.
     fn to_sql(self, buf: &mut Vec<u8>) -> IsNull;
 }
 
+/// [ToSql] is implemented for `Option<T>` where `T` implements `ToSql`. An `Option<T>` 
+/// represents a nullable SQL value.
 impl<T, DB> ToSql<DB> for Option<T>
 where
     DB: Backend + HasSqlType<T>,