+=item Return values
+
+C<with_transaction> adopts the behaviour of C<eval> in that it returns the
+result of the inner block, and C<undef> if an error occured. This way you can
+use the same pattern you would normally use with C<eval> for
+C<with_transaction>:
+
+ SL::DB->client->with_transaction(sub {
+ # do stuff
+ # and return nominal true value
+ 1;
+ }) or do {
+ # transaction error handling
+ my $error = SL::DB->client->error;
+ }
+
+or you can use it to safely calulate things.
+
+=item Error handling
+
+The original L<Rose::DB/do_transaction> gobbles up all execptions and expects
+the caller to manually check return value and error, and then to process all
+exceptions as strings. This is very fragile and generally a step backwards from
+proper exception handling.
+
+C<with_transaction> only gobbles up exception that are used to signal an
+error in the transaction, and returns undef on those. All other exceptions
+bubble out of the transaction like normal, so that it is transparent to typoes,
+runtime exceptions and other generally wanted things.
+
+If you just use the snippet above, your code will catch everything related to
+the transaction aborting, but will not catch other errors that might have been
+thrown. The transaction will be rollbacked in both cases.
+
+If you want to play nice in case your transaction is embedded in another
+transaction, just rethrow the error:
+
+ $db->with_transaction(sub {
+ # code deep in the engine
+ 1;
+ }) or die $db->error;
+
+=back