Some documentation cleanup

src/postgres/lib.rs

@@ -554,6 +554,8 @@ impl PostgresConnection {
 
     /// A convenience wrapper around `try_connect`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error connecting to the database.
     pub fn connect(url: &str) -> PostgresConnection {
         match PostgresConnection::try_connect(url) {
@@ -588,6 +590,8 @@ impl PostgresConnection {
 
     /// A convenience wrapper around `try_prepare`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error preparing the statement.
     pub fn prepare<'a>(&'a self, query: &str) -> NormalPostgresStatement<'a> {
         match self.try_prepare(query) {
@@ -627,6 +631,8 @@ impl PostgresConnection {
 
     /// A convenience wrapper around `try_update`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error preparing or executing the statement.
     pub fn update(&self, query: &str, params: &[&ToSql]) -> uint {
         match self.try_update(query, params) {
@@ -772,12 +778,16 @@ pub trait PostgresStatement {
     ///
     /// If the statement does not modify any rows (e.g. SELECT), 0 is returned.
     ///
+    /// # Failure
+    ///
     /// Fails if the number or types of the provided parameters do not match
     /// the parameters of the statement.
     fn try_update(&self, params: &[&ToSql]) -> Result<uint, PostgresDbError>;
 
     /// A convenience function wrapping `try_update`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error executing the statement.
     fn update(&self, params: &[&ToSql]) -> uint {
         match self.try_update(params) {
@@ -789,6 +799,8 @@ pub trait PostgresStatement {
     /// Attempts to execute the prepared statement, returning an iterator over
     /// the resulting rows.
     ///
+    /// # Failure
+    ///
     /// Fails if the number or types of the provided parameters do not match
     /// the parameters of the statement.
     fn try_query<'a>(&'a self, params: &[&ToSql])
@@ -796,6 +808,8 @@ pub trait PostgresStatement {
 
     /// A convenience function wrapping `try_query`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error executing the statement.
     fn query<'a>(&'a self, params: &[&ToSql]) -> PostgresResult<'a> {
         match self.try_query(params) {
@@ -1018,6 +1032,8 @@ impl<'self> TransactionalPostgresStatement<'self> {
     /// will be pulled from the database in batches of `row_limit` as needed.
     /// If `row_limit` is 0, `try_lazy_query` is equivalent to `try_query`.
     ///
+    /// # Failure
+    ///
     /// Fails if the number or types of the provided parameters do not match
     /// the parameters of the statement.
     pub fn try_lazy_query<'a>(&'a self, row_limit: uint, params: &[&ToSql])
@@ -1027,6 +1043,8 @@ impl<'self> TransactionalPostgresStatement<'self> {
 
     /// A convenience wrapper around `try_lazy_query`.
     ///
+    /// # Failure
+    ///
     /// Fails if there was an error executing the statement.
     pub fn lazy_query<'a>(&'a self, row_limit: uint, params: &[&ToSql])
             -> PostgresResult<'a> {
@@ -1145,6 +1163,8 @@ impl<'self, I: RowIndex, T: FromSql> Index<I, T> for PostgresRow<'self> {
 pub trait RowIndex {
     /// Returns the index of the appropriate column.
     ///
+    /// # Failure
+    ///
     /// Fails if there is no corresponding column.
     fn idx(&self, stmt: &NormalPostgresStatement) -> uint;
 }

src/postgres/pool.rs

@@ -132,7 +132,7 @@ impl PooledPostgresConnection {
         self.conn.get_ref().update(query, params)
     }
 
-    /// `PostgresConnection::in_transaction`.
+    /// Like `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

@@ -127,6 +127,8 @@ pub trait FromSql {
     ///
     /// If the value was `NULL`, the buffer will be `None`.
     ///
+    /// # Failure
+    ///
     /// Fails if this type can not be created from the provided Postgres type.
     fn from_sql(ty: PostgresType, raw: &Option<~[u8]>) -> Self;
 }
@@ -222,6 +224,8 @@ pub trait ToSql {
     /// Converts the value of `self` into a format appropriate for the Postgres
     /// backend.
     ///
+    /// # Failure
+    ///
     /// Fails if this type cannot be converted into the specified Postgres
     /// type.
     fn to_sql(&self, ty: PostgresType) -> (Format, Option<~[u8]>);