[Catalyst-commits] r12373 - trunk/examples/CatalystAdvent/root/2009/pen

[zarquon at dev.catalyst.perl.org]

Author: zarquon
Date: 2009-12-14 23:49:22 +0000 (Mon, 14 Dec 2009)
New Revision: 12373

Modified:
   trunk/examples/CatalystAdvent/root/2009/pen/dbic-txn.pod
Log:
copy edits

Modified: trunk/examples/CatalystAdvent/root/2009/pen/dbic-txn.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/pen/dbic-txn.pod	2009-12-14 23:48:59 UTC (rev 12372)
+++ trunk/examples/CatalystAdvent/root/2009/pen/dbic-txn.pod	2009-12-14 23:49:22 UTC (rev 12373)
@@ -6,15 +6,16 @@
 =head2 Atomicity
 
 Often a Model operation, in the sense of business logic, requires a group of
-related actual database operations. You want these to be atomic, that is if any
-single operation in the group fails, then the whole group fails and your data
-remains consistent.
+closely related (or dependent) database operations.  These should be
+atomic.  That is if any single operation in the group fails, then the whole
+group of operations will fail and your data remains consistent.
 
 Suppose you wrote some code such as:
 
     sub create_user : Local {
         my ($self, $c) = @_;
 
+        # we love hash slices
         my ($username, $first_name, $last_name, $token_id) =
             @{ $c->req->params }{qw/username first_name last_name token_id/};
 
@@ -34,13 +35,13 @@
         $c->flash->{message} = "Created user ${username}!";
     }
 
-Looks perfectly reasonable, but there are two operations here, one which
+This looks perfectly reasonable, but there are two operations here, one which
 creates a user entry, and one that creates a token entry for it.
 
-What could possibly go wrong between them? Lots of things, such as your web
-server going down in flames, your database server crashing, and so on. While
-the chances of this are slight, repairing erroneous data in a database is a
-painful, expensive and hazardous process.
+What could possibly go wrong between them? Lots of things, such as the web
+server going down in flames, the database server crashing, alien invasion, and
+so on. While the chances of this are small, repairing erroneous data in a
+database is a painful, expensive and hazardous process.
 
 Also we had to use an unnatural control flow here, normally we'd validate the
 token before it is created, rather than before the user is created.
@@ -59,23 +60,23 @@
         $user->add_to_tokens({ token_id => $token_id });
     });
 
-Now the operation is atomic, your user entries as well as any related
+Now that the operation is atomic, your user entries as well as any related
 entries are guaranteed to be consistent, and we are using a more natural
 control flow.
 
 Any exceptions from C<txn_do> are re-thrown and a C<ROLLBACK> is issued,
-leaving the database untouched by the enclosed code.
+leaving the database untouched by the code enclosed by the transaction.
 
 Exceptions can be cleaned up in your C<end> handler, by getting them from C<<
 $c->error >>, or using something like
-L<Catalyst::Action::RenderView::ErrorHandler>. But in some cases you may want
-to wrap them in an eval (or one of L<Try::Catch>, L<Try::Tiny>) to detach in
-order to, for example, short-circuit a chain.
+L<Catalyst::Action::RenderView::ErrorHandler>. However, in some cases you may
+want to wrap them in an eval (or one of L<Try::Catch>, L<Try::Tiny>) to detach
+in order to short-circuit a chain for example.
 
 It is also recommended to factor out database code into the relevant
-L<DBIx::Class::ResultSet> methods. ResultSet classes go into e.g. the
-C<lib/MyApp/Schema/ResultSet> directory, next to your C<Result> directory and
-inherit from C<DBIx::Class::ResultSet>.
+L<DBIx::Class::ResultSet> methods. ResultSet classes go into the
+C<lib/MyApp/Schema/ResultSet> directory (for example), next to the C<Result>
+directory and inherit from C<DBIx::Class::ResultSet>.
 
 =head2 txn_scope_guard
 
@@ -134,7 +135,7 @@
 and Sybase databases.
 
 You have to add C<< auto_savepoint => 1 >> to your C<connect_info> to enable
-this feature, see L<DBIx::Class::Storage::DBI> for details.
+this feature:  see L<DBIx::Class::Storage::DBI> for details.
 
     sub validate_batch : Local {
         my ($self, $c) = @_;