add UseBlock documentation

Author: ivan-klass

scalasql/test/src/api/TransactionTests.scala

@@ -587,6 +587,27 @@ trait TransactionTests extends ScalaSqlSuite {
       }
     }
 
+    test("useBlock") - checker.recorded(
+      """
+      Both `transaction` and `savepoint` accessors are actually returning a special `UseBlock[...]` types.
+      When you call `transaction(use)` it desugars into `transaction.apply(use)` that provides a default
+      resource-style management - it creates a transaction (or savepoint), runs `use` block immediately, then releases
+      (commits or rolls back) the transaction.
+
+      If you need more control over the lifecycle, you may use transaction.allocate() method that returns
+      `(resource, releaseFunction)` pair.
+      This is especially useful when delaying side-effects with FP libraries like cats-effect or ZIO.
+      **Important:** `allocate()` is impure and must be delayed in that case also.
+      The `dbClient.transaction` expression itself does not perform any side-effects, it just creates closures.
+      """,
+      Text {
+        val transactionBlock: scalasql.core.UseBlock[DbApi.Txn] = dbClient.transaction
+
+        def createTransactionWithReleseFunction(): (DbApi.Txn, Option[Throwable] => Unit) =
+          transactionBlock.allocate()
+      }
+    )
+
     test("listener") {
       test("beforeCommit and afterCommit are called under normal circumstances") {
         val listener = new StubTransactionListener()