-One big difference to L<Rose::DB/do_transaction> is the return code
-handling. If a transaction is already active then C<with_transaction>
-simply returns the result of calling C<$code_ref> as-is.
+There are two big differences between C<with_transaction> and
+L<Rose::DB/do_transaction>: the handling of an already-running
+transaction and the handling of return values.
+
+The first difference revolves around when a transaction is started and
+committed/rolled back. Rose's C<do_transaction> will always start one,
+then execute the code reference and commit afterwards (or roll back if
+an exception occurs).
+
+This prevents the caller from combining several pieces of code using
+C<do_transaction> reliably as results committed by an inner
+transaction will be permanent even if the outer transaction is rolled
+back.
+
+Therefore our C<with_transaction> works differently: it will only
+start a transaction if no transaction is currently active on the
+database connection.