     // -----------------------------------------------------------------------------------------------------------------
     // MARK:  Transactions
     
+    /// Result type used to commit or rollback transactions and savepoints.
     public enum TransactionResult {
         case Commit
         case Rollback
         case Failed(NSError)
     }
 
+    /// Begins a database transaction by executing a BEGIN TRANSACTION statement. Transactions cannot be nested. If
+    /// nested operations are needed, consider using savepoints instead.
+    ///
+    /// :returns: `true` if the transaction began, `false` otherwise.
     public func beginTransaction(error:NSErrorPointer = nil) -> Bool {
         return execute("BEGIN TRANSACTION", error: error)
     }
 
+    /// Ends the current transaction and discards changes since the transaction began. All savepoints are also rolled
+    /// back. See sqlite docs for details on transaction support.
+    ///
+    /// :returns: `true` if the transaction was rolled back, `false` otherwise.
     public func rollback(error:NSErrorPointer = nil) -> Bool {
         return execute("ROLLBACK", error: error)
     }
 
+    /// Commits the current transaction and persists changes since the transaction began. All savepoints are also
+    /// committed. See sqlite docs for details on transaction support.
+    ///
+    /// :returns: `true` if the transaction was committed, `false` otherwise.
     public func commit(error:NSErrorPointer = nil) -> Bool {
         return execute("COMMIT", error: error)
     }
 
+    ///
+    /// Begins a transaction, invokes the provided closure, and uses its result to determine how to terminate the
+    /// transaction. Using this method is more concise than creating and managing the transaction yourself. For example:
+    /// 
+    ///     let result = db.transaction {
+    ///         var error : NSError?
+    ///         if let rowId = $0.insertInto("people", values:["name":"Agnes Pigott"], error:&error) {
+    ///             return .Failed(error)
+    ///         }
+    ///
+    ///         // more SQL statements...
+    ///
+    ///         return .Commit
+    ///     }
+    ///
+    /// :param: block   The operation to perform within the transaction. It should not close the transaction itself, but
+    ///                 instead return a TransactionResult.
+    /// :returns:       The result of the transaction. This should nearly always be the same value returned by the
+    ///                 block, except when the BEGIN, ROLLBACK, or COMMIT statements fail.
+    ///
     public func transaction(block:(db:Database)->TransactionResult) -> TransactionResult {
         var localError : NSError?
         var didBegin = beginTransaction(error: &localError)

    // -----------------------------------------------------------------------------------------------------------------
    // MARK:  Query
    
    public func query(sqlString:String, error:NSErrorPointer) -> Statement? {
        let sqliteStatement = prepareSqliteStatement(sqlString, error:error)
        if sqliteStatement == nil {
            return nil
        }
        
        var statement = Statement(database: self, sqliteStatement: sqliteStatement)
        statements.append(WeakStatement(statement))
        return statement
    }
    
    public func query(sqlString:String, parameters:[Bindable?]?, error:NSErrorPointer) -> Statement? {
        if let statement = query(sqlString, error:error) {
            if parameters?.count > 0 {
                var boundSuccessfully = statement.bind(parameters!, error:error)
                if !boundSuccessfully {

        return sqliteStatement
    }
    
    ///
    /// Compiles a SQL string into a Statement, which can then be used to execute the SQL against the database.
    /// Statement objects can be executed multiple times, and are more efficient when executing the same query or update
    /// multiple times. See the Statement object for details, including providing parameters.
    ///
    /// :param:     sqlString   A SQL statement to compile.
    /// :param:     error       An error pointer to set if an error occurs. May be `nil`.
    /// :returns:               The compiled SQL as a Statement. This Statement must be closed when it is no longer
    ///                         needed. On error, `nil` will be returned and an NSError object will be provided via the
    ///                         `error` parameter.
    ///
    public func prepareStatement(sqlString:String, error:NSErrorPointer) -> Statement? {
        let sqliteStatement = prepareSqliteStatement(sqlString, error:error)
        if sqliteStatement == nil {
