From 83ad9147748c676637aebe515a62151941e06a85 Mon Sep 17 00:00:00 2001 From: Steven Fackler Date: Sun, 29 Sep 2013 19:47:30 -0700 Subject: [PATCH] Documentation for everything else --- src/postgres/error.rs | 1 + src/postgres/lib.rs | 2 ++ src/postgres/message.rs | 2 ++ src/postgres/pool/mod.rs | 34 ++++++++++++++++++++++++---------- src/postgres/types.rs | 33 +++++++++++++++++++++++++++++++++ 5 files changed, 62 insertions(+), 10 deletions(-) diff --git a/src/postgres/error.rs b/src/postgres/error.rs index 0cf26796..fa31a430 100644 --- a/src/postgres/error.rs +++ b/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,)+ diff --git a/src/postgres/lib.rs b/src/postgres/lib.rs index abe5c8b8..285c70ab 100644 --- a/src/postgres/lib.rs +++ b/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; diff --git a/src/postgres/message.rs b/src/postgres/message.rs index a8ef0396..b5581868 100644 --- a/src/postgres/message.rs +++ b/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, diff --git a/src/postgres/pool/mod.rs b/src/postgres/pool/mod.rs index bda220d4..309fbb26 100644 --- a/src/postgres/pool/mod.rs +++ b/src/postgres/pool/mod.rs @@ -26,6 +26,9 @@ 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 { @@ -33,6 +36,10 @@ pub struct PostgresConnectionPool { } 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 { let mut pool = InnerConnectionPool { @@ -52,6 +59,9 @@ 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, @@ -59,8 +69,10 @@ impl PostgresConnectionPool { } } - pub fn try_get_connection(&self) -> Result { + /// 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, 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 { 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(&self, blk: &fn(&PostgresTransaction) -> T) -> T { self.conn.get_ref().in_transaction(blk) } diff --git a/src/postgres/types.rs b/src/postgres/types.rs index dab28fcb..8f089b5a 100644 --- a/src/postgres/types.rs +++ b/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]>); }