Documentation for everything else

Author: sfackler

src/postgres/error.rs

@@ -2,6 +2,7 @@ macro_rules! make_errors(
     ($($code:pat => $error:ident),+) => (
         // TODO: Get rid of this module when mozilla/rust#4375 is fixed
         pub mod hack {
+            /// SQLSTATE error codes
             #[deriving(ToStr, Eq)]
             pub enum PostgresSqlState {
                 $($error,)+

src/postgres/lib.rs

@@ -4,6 +4,8 @@
 // Needed for rustdoc-ng
 #[link(name="postgres")];
 
+#[warn(missing_doc)];
+
 extern mod extra;
 
 use extra::container::Deque;

src/postgres/message.rs

@@ -1,3 +1,5 @@
+#[allow(missing_doc)];
+
 use std::str;
 use std::rt::io::{Decorator, Reader, Writer};
 use std::rt::io::extensions::{ReaderUtil, ReaderByteConversions,

src/postgres/pool/mod.rs

@@ -26,13 +26,20 @@ impl InnerConnectionPool {
     }
 }
 
+/// A simple fixed-size Postgres connection pool.
+///
+/// It can be shared across tasks.
 // Should be a newtype, but blocked by mozilla/rust#9155
 #[deriving(Clone)]
 pub struct PostgresConnectionPool {
     priv pool: MutexArc<InnerConnectionPool>
 }
 
 impl PostgresConnectionPool {
+    /// Attempts to create a new pool with the specified number of connections.
+    ///
+    /// Returns an error if the specified number of connections cannot be
+    /// created.
     pub fn try_new(url: &str, pool_size: uint)
             -> Result<PostgresConnectionPool, PostgresConnectError> {
         let mut pool = InnerConnectionPool {
@@ -52,15 +59,20 @@ impl PostgresConnectionPool {
         })
     }
 
+    /// A convenience function wrapping `try_new`.
+    ///
+    /// Fails if the pool cannot be created.
     pub fn new(url: &str, pool_size: uint) -> PostgresConnectionPool {
         match PostgresConnectionPool::try_new(url, pool_size) {
             Ok(pool) => pool,
             Err(err) => fail!("Unable to initialize pool: %s", err.to_str())
         }
     }
 
-    pub fn try_get_connection(&self) -> Result<PooledPostgresConnection,
-                                               PostgresConnectError> {
+    /// Retrieves a connection from the pool.
+    ///
+    /// If all connections are in use, blocks until one becomes available.
+    pub fn get_connection(&self) -> PooledPostgresConnection {
         let conn = unsafe {
             do self.pool.unsafe_access_cond |pool, cvar| {
                 while pool.pool.is_empty() {
@@ -71,20 +83,17 @@ impl PostgresConnectionPool {
             }
         };
 
-        Ok(PooledPostgresConnection {
+        PooledPostgresConnection {
             pool: self.clone(),
             conn: Some(conn)
-        })
-    }
-
-    pub fn get_connection(&self) -> PooledPostgresConnection {
-        match self.try_get_connection() {
-            Ok(conn) => conn,
-            Err(err) => fail!("Unable to get connection: %s", err.to_str())
         }
     }
 }
 
+/// A Postgres connection pulled from a connection pool.
+///
+/// It will be returned to the pool when it falls out of scope, even due to
+/// task failure.
 pub struct PooledPostgresConnection {
     priv pool: PostgresConnectionPool,
     // TODO remove the Option wrapper when drop takes self by value
@@ -102,24 +111,29 @@ impl Drop for PooledPostgresConnection {
 }
 
 impl PooledPostgresConnection {
+    /// Like `PostgresConnection::try_prepare`.
     pub fn try_prepare<'a>(&'a self, query: &str)
             -> Result<NormalPostgresStatement<'a>, PostgresDbError> {
         self.conn.get_ref().try_prepare(query)
     }
 
+    /// Like `PostgresConnection::prepare`.
     pub fn prepare<'a>(&'a self, query: &str) -> NormalPostgresStatement<'a> {
         self.conn.get_ref().prepare(query)
     }
 
+    /// Like `PostgresConnection::try_update`.
     pub fn try_update(&self, query: &str, params: &[&ToSql])
             -> Result<uint, PostgresDbError> {
         self.conn.get_ref().try_update(query, params)
     }
 
+    /// Like `PostgresConnection::update`.
     pub fn update(&self, query: &str, params: &[&ToSql]) -> uint {
         self.conn.get_ref().update(query, params)
     }
 
+    /// `PostgresConnection::in_transaction`.
     pub fn in_transaction<T>(&self, blk: &fn(&PostgresTransaction) -> T) -> T {
         self.conn.get_ref().in_transaction(blk)
     }

src/postgres/types.rs

@@ -9,6 +9,7 @@ use std::rt::io::extensions::{WriterByteConversions, ReaderByteConversions};
 use std::rt::io::mem::{MemWriter, BufReader};
 use std::str;
 
+/// A Postgres OID
 pub type Oid = i32;
 
 // Values from pg_type.h
@@ -34,27 +35,45 @@ static NSEC_PER_USEC: i64 = 1_000;
 // Number of seconds from 1970-01-01 to 2000-01-01
 static TIME_SEC_CONVERSION: i64 = 946684800;
 
+/// A Postgres type
 #[deriving(Eq)]
 pub enum PostgresType {
+    /// BOOL
     PgBool,
+    /// BYTEA
     PgByteA,
+    /// "char"
     PgChar,
+    /// INT8/BIGINT
     PgInt8,
+    /// INT2/SMALLINT
     PgInt2,
+    /// INT4/INT
     PgInt4,
+    /// TEXT
     PgText,
+    /// JSON
     PgJson,
+    /// FLOAT4/REAL
     PgFloat4,
+    /// FLOAT8/DOUBLE PRECISION
     PgFloat8,
+    /// TIMESTAMP
     PgTimestamp,
+    /// TIMESTAMP WITH TIME ZONE
     PgTimestampZ,
+    /// CHAR(n)/CHARACTER(n)
     PgCharN,
+    /// VARCHAR/CHARACTER VARYING
     PgVarchar,
+    /// UUID
     PgUuid,
+    /// An unknown type along with its OID
     PgUnknownType(Oid)
 }
 
 impl PostgresType {
+    /// Creates a PostgresType from a Postgres OID.
     pub fn from_oid(oid: Oid) -> PostgresType {
         match oid {
             BOOLOID => PgBool,
@@ -76,6 +95,7 @@ impl PostgresType {
         }
     }
 
+    /// Returns the wire format needed for the value of `self`.
     pub fn result_format(&self) -> Format {
         match *self {
             PgUnknownType(*) => Text,
@@ -84,6 +104,7 @@ impl PostgresType {
     }
 }
 
+/// The wire format of a Postgres value
 pub enum Format {
     Text = 0,
     Binary = 1
@@ -98,7 +119,13 @@ macro_rules! check_types(
     )
 )
 
+/// A trait for things that can be created from a Postgres value
 pub trait FromSql {
+    /// Creates a new value of this type from a buffer of Postgres data.
+    ///
+    /// If the value was `NULL`, the buffer will be `None`.
+    ///
+    /// Fails if this type can not be created from the provided Postgres type.
     fn from_sql(ty: PostgresType, raw: &Option<~[u8]>) -> Self;
 }
 
@@ -188,7 +215,13 @@ from_map_impl!(PgTimestamp | PgTimestampZ, Timespec, |buf| {
 })
 from_option_impl!(Timespec)
 
+/// A trait for types that can be converted into Postgres values
 pub trait ToSql {
+    /// Converts the value of `self` into a format appropriate for the Postgres
+    /// backend.
+    ///
+    /// Fails if this type cannot be converted into the specified Postgres
+    /// type.
     fn to_sql(&self, ty: PostgresType) -> (Format, Option<~[u8]>);
 }