better hook docs

diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm
index cbba2a0..055f89a 100644 (file)
--- a/lib/DBIx/Class/ResultSource.pm
+++ b/lib/DBIx/Class/ResultSource.pm
@@ -1385,11 +1385,17 @@ should not be used.  It will be removed before 1.0.
 
   __PACKAGE__->column_info_from_storage(1);
 
-=cut
+=head2 sqlt_deploy_callback
 
-=head2 sqlt_deploy_hook
+An attribute which contains the callback to trigger on L</sqlt_deploy_hook>.
+Defaults to L</default_sqlt_deploy_hook>. Can be a code reference or the name
+of a method in the current result class. You would change the default value
+in case you want to share a hook between several result sources, or if you 
+want to use a result source without a declared result class.
 
-=over 4
+=head2 default_sqlt_deploy_hook
+
+=over
 
 =item Arguments: $source, $sqlt_table
 
@@ -1397,67 +1403,58 @@ should not be used.  It will be removed before 1.0.
 
 =back
 
-An optional sub which you can declare in your own Result class that will get 
-passed the L<SQL::Translator::Schema::Table> object when you deploy the schema
-via L</create_ddl_dir> or L</deploy>.
-
-This is useful to make L<SQL::Translator> create non-unique indexes, or set
-table options such as C<Engine=INNODB>. For an example of what you can do with
-this, see
+Proxies its arguments to a C<sqlt_deploy_hook> method on the C<result_class>
+if such a method exists. This is useful to make L<SQL::Translator> create
+non-unique indexes, or set table options such as C<Engine=INNODB>. For 
+examples of what you can do with this, see
 L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
 
-Note that sqlt_deploy_hook is called by 
-L<DBIx::Class::Schema/deployment_statements>, which in turn is called before
-L<DBIx::Class::Schema/deploy>. Therefore the hook can be used only to manipulate
-the L<SQL::Translator::Table> object before it is turned into SQL fed to the
-database. If you want to execute post-deploy statements which can not be generated
-by L<SQL::Translator>, the currently suggested method is to overload
-L<DBIx::Class::Storage/deploy> and use L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
-
-Starting from DBIC 0.08100 a simple hook is inherited by all result sources, which
-invokes the method or coderef specified in L</sqlt_deploy_callback>. You can still
-overload this method like in older DBIC versions without any compatibility issues.
-
 =cut
 
-sub sqlt_deploy_hook {
+sub default_sqlt_deploy_hook {
   my $self = shift;
-  if ( my $hook = $self->sqlt_deploy_callback) {
-    $self->$hook(@_);
+
+  my $class = $self->result_class;
+
+  if ($class and $class->can('sqlt_deploy_hook')) {
+    $class->sqlt_deploy_hook(@_);
   }
 }
 
-=head2 sqlt_deploy_callback
 
-An attribute which contains the callback to trigger on C<sqlt_deploy_hook>.
-Defaults to C<default_sqlt_deploy_hook>. Can be a code reference or the name
-of a method in a result class. You would change the default value in case you
-want to share a hook between several result sources, or if you want to use a
-result source without a declared result class.
+=head2 sqlt_deploy_hook
 
-=head2 default_sqlt_deploy_hook($table)
+=over 4
 
-Delegates to a an optional C<sqlt_deploy_hook> method on the C<result_class>.
+=item Arguments: $source, $sqlt_table
 
-This will get passed the L<SQL::Translator::Schema::Table> object when you
-deploy the schema via L</create_ddl_dir> or L</deploy>.
+=item Return value: undefined
 
-For an example of what you can do with this, see 
-L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
+=back
 
-=cut
+This is the entry point invoked by L<SQL::Translator::Parser::DBIx::Class>
+during the execution of L<DBIx::Class::Storage::DBI/deployment_statements>.
+Delegates to the method name or code reference specified in
+L</sqlt_deploy_callback>.
 
-sub default_sqlt_deploy_hook {
-  my $self = shift;
+Note that the code is called by 
+L<DBIx::Class::Storage::DBI/deployment_statements>, which in turn is called
+before L<DBIx::Class::Schema/deploy>. Therefore the hook can be used only
+to manipulate the L<SQL::Translator::Table> object before it is turned into
+SQL fed to the database. If you want to execute post-deploy statements which
+currently can can not be generated by L<SQL::Translator>, the suggested
+method is to overload L<DBIx::Class::Storage/deploy> and use
+L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
 
-  my $class = $self->result_class;
+=cut
 
-  if ($class and $class->can('sqlt_deploy_hook')) {
-    $class->sqlt_deploy_hook(@_);
+sub sqlt_deploy_hook {
+  my $self = shift;
+  if ( my $hook = $self->sqlt_deploy_callback) {
+    $self->$hook(@_);
   }
 }
 
-
 =head1 AUTHORS
 
 Matt S. Trout <mst@shadowcatsystems.co.uk>