Docs for com.github.mauricio.async.db.pool.ConnectionPool regarding transactions still right? #237

Either I missunderstand the code or the docs of com.github.mauricio.async.db.pool.ConnectionPool are pointing into the wrong direction/is inconsistent regarding transactions and long running queries.

The downside of this is that you should not start transactions or any kind of long running process
in this object as the object will be sent back to the pool right after executing a query. If you
need to start transactions you will have to take an object from the pool, do it and then give it
back manually.

Docs of com.github.mauricio.async.db.pool.ConnectionPool#inTransaction states

Picks one connection and executes an (asynchronous) function on it within a transaction block. If the function completes successfully, the transaction is committed, otherwise it is aborted.
Either way, the connection is returned to the pool on completion.

This matches with the implementation which states:

• take connection from pool
• execute closure passed to inTransaction with taken connection
• evaluate Future of closure result, giveBack the connection onComplete

// com.github.mauricio.async.db.pool.ConnectionPool#inTransaction
override def inTransaction[A](f : Connection => Future[A])(implicit context : ExecutionContext = executionContext) : Future[A] =
    this.use(_.inTransaction[A](f)(context))(executionContext)

and further

// com.github.mauricio.async.db.pool.AsyncObjectPool#use
def use[A](f: (T) => Future[A])(implicit executionContext: ExecutionContext): Future[A] =
    take.flatMap { item =>
      val p = Promise[A]()
      try {
        f(item).onComplete { r =>
          giveBack(item).onComplete { _ =>
            p.complete(r)
          }
        }
      } catch {
        // calling f might throw exception.
        // in that case the item will be removed from the pool if identified as invalid by the factory.
        // the error returned to the user is the original error thrown by f.
        case error: Throwable =>
          giveBack(item).onComplete { _ =>
            p.failure(error)
          }
      }

      p.future
    }