From 47458d49e54961c85ac5746c6ab8530d08dbef8c Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Thu, 19 Nov 2020 00:05:24 +0000
Subject: [PATCH] Added documentation for Rollback

---
 docs/connection.rst              |  4 ++++
 docs/from_pg2.rst                |  2 ++
 docs/usage.rst                   | 37 +++++++++++++++++++++++++-------
 psycopg3/psycopg3/transaction.py |  2 +-
 4 files changed, 36 insertions(+), 9 deletions(-)

diff --git a/docs/connection.rst b/docs/connection.rst
index 03cb4441f..abe6b08fe 100644
--- a/docs/connection.rst
+++ b/docs/connection.rst
@@ -141,6 +141,8 @@ Connection support objects
 .. autoclass:: Notify
     :members: channel, payload, pid
 
+.. rubric:: Objects involved in :ref:`transactions`
+
 .. autoclass:: Transaction(connection: Connection, savepoint_name: Optional[str] = None, force_rollback: bool = False)
 
     .. autoproperty:: savepoint_name
@@ -148,3 +150,5 @@ Connection support objects
         :annotation: Connection
 
 .. autoclass:: AsyncTransaction(connection: AsyncConnection, savepoint_name: Optional[str] = None, force_rollback: bool = False)
+
+.. autoexception:: Rollback
diff --git a/docs/from_pg2.rst b/docs/from_pg2.rst
index 130b2445d..29eb3865f 100644
--- a/docs/from_pg2.rst
+++ b/docs/from_pg2.rst
@@ -85,6 +85,8 @@ files.
 What's new in psycopg3
 ======================
 
+TODO: to be completed
+
 - `asyncio` support.
 - Several data types are adapted out-of-the-box: uuid, network, range, bytea,
   array of any supported type are dealt with automatically.
diff --git a/docs/usage.rst b/docs/usage.rst
index fc24d3187..eb45f9093 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -129,7 +129,7 @@ TODO: lift from psycopg2 docs
 
 
 .. index::
-    pair: Query; Parameters
+    pair: Binary; Parameters
 
 .. _binary-data:
 
@@ -208,11 +208,13 @@ accounts unbalanced:
     # The transaction is now committed
 
 Transaction blocks can also be nested (internal transaction blocks are
-implemented using :sql:`SAVEPOINT`): an exception raised inside an inner block
-has a chance of being handled and not fail completely outer operations. The
-following is an example where a series of operation interact with the
-database. Operations are allowed to fail, and we want to store the number of
-operations successfully processed too.
+implemented using SAVEPOINT__): an exception raised inside an inner block
+has a chance of being handled and not completely fail outer operations. The
+following is an example where a series of operations interact with the
+database: operations are allowed to fail, plus we also want to store the
+number of operations successfully processed.
+
+.. __: https://www.postgresql.org/docs/current/sql-savepoint.html
 
 .. code:: python
 
@@ -232,10 +234,29 @@ operations successfully processed too.
 If `!unreliable_operation()` causes an error, including an operation causing a
 database error, all its changes will be reverted. The exception bubbles up
 outside the block: in the example it is intercepted by the `!try` so that the
-loop can complete. The outermost loop is unaffected (unless other errors
+loop can complete. The outermost block is unaffected (unless other errors
 happen there).
 
-.. TODO: Document Rollback or remove it
+You can also write code to explicitly roll back any currently active
+transaction block, by raising the `Rollback` exception. The exception "jumps"
+to the end of a transaction block, rolling back its transaction but allowing
+the program execution to continue from there. By default the exception rolls
+back the innermost transaction block, but any current block can be specified
+as the target. In the following example, an hypothetical `!CancelCommand`
+may stop the processing and cancel any operation previously performed,
+but not entirely committed yet.
+
+.. code:: python
+
+    with conn.transaction() as outer_tx:
+        for command in commands():
+            with conn.transaction() as inner_tx:
+                if isinstance(command, CancelCommand):
+                    raise psycopg3.Rollback(outer_tx)
+            process_command(command)
+
+    # If `Rollback` is raised, it would propagate only up to this block,
+    # and the program would continue from here with no exception.
 
 
 .. index::
diff --git a/psycopg3/psycopg3/transaction.py b/psycopg3/psycopg3/transaction.py
index 63a098f02..3ef83ef12 100644
--- a/psycopg3/psycopg3/transaction.py
+++ b/psycopg3/psycopg3/transaction.py
@@ -21,7 +21,7 @@ _log = logging.getLogger(__name__)
 
 class Rollback(Exception):
     """
-    Exit the current Transaction context immediately and rollback any changes
+    Exit the current `Transaction` context immediately and rollback any changes
     made within this context.
 
     If a transaction context is specified in the constructor, rollback
-- 
2.47.2