From: Peter Rabbitson <ribasushi@cpan.org>
Date: Fri, 24 Jun 2016 16:31:01 +0000 (+0200)
Subject: Fill in missing documentation in ::Schema / ::ResultSource
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=759a7f44196c25be4409dc417be9160048d1f261;p=dbsrgits%2FDBIx-Class.git

Fill in missing documentation in ::Schema / ::ResultSource
---

diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm
index 725f30d..a7645ef 100644
--- a/lib/DBIx/Class/ResultSource.pm
+++ b/lib/DBIx/Class/ResultSource.pm
@@ -1098,12 +1098,15 @@ Store a collection of resultset attributes, that will be set on every
 L<DBIx::Class::ResultSet> produced from this result source.
 
 B<CAVEAT>: C<resultset_attributes> comes with its own set of issues and
-bugs! While C<resultset_attributes> isn't deprecated per se, its usage is
-not recommended!
+bugs! Notably the contents of the attributes are B<entirely static>, which
+greatly hinders composability (things like L<current_source_alias
+|DBIx::Class::ResultSet/current_source_alias> can not possibly be respected).
+While C<resultset_attributes> isn't deprecated per se, you are strongly urged
+to seek alternatives.
 
 Since relationships use attributes to link tables together, the "default"
 attributes you set may cause unpredictable and undesired behavior.  Furthermore,
-the defaults cannot be turned off, so you are stuck with them.
+the defaults B<cannot be turned off>, so you are stuck with them.
 
 In most cases, what you should actually be using are project-specific methods:
 
diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 3bcc37f..9b5b56b 100644
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -18,12 +18,16 @@ use Devel::GlobalDestruction;
 use namespace::clean;
 
 __PACKAGE__->mk_group_accessors( inherited => qw( storage exception_action ) );
-__PACKAGE__->mk_classaccessor('class_mappings' => {});
-__PACKAGE__->mk_classaccessor('source_registrations' => {});
 __PACKAGE__->mk_classaccessor('storage_type' => '::DBI');
 __PACKAGE__->mk_classaccessor('stacktrace' => $ENV{DBIC_TRACE} || 0);
 __PACKAGE__->mk_classaccessor('default_resultset_attributes' => {});
 
+# These two should have been private from the start but too late now
+# Undocumented on purpose, hopefully it won't ever be necessary to
+# screw with them
+__PACKAGE__->mk_classaccessor('class_mappings' => {});
+__PACKAGE__->mk_classaccessor('source_registrations' => {});
+
 =head1 NAME
 
 DBIx::Class::Schema - composable schemas
@@ -427,6 +431,30 @@ both types of refs here in order to play nice with your
 Config::[class] or your choice. See
 L<DBIx::Class::Storage::DBI::Replicated> for an example of this.
 
+=head2 default_resultset_attributes
+
+=over 4
+
+=item Arguments: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
+
+=item Return Value: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
+
+=item Default value: None
+
+=back
+
+Like L<DBIx::Class::ResultSource/resultset_attributes> stores a collection
+of resultset attributes, to be used as defaults for B<every> ResultSet
+instance schema-wide. The same list of CAVEATS and WARNINGS applies, with
+the extra downside of these defaults being practically inescapable: you will
+B<not> be able to derive a ResultSet instance with these attributes unset.
+
+Example:
+
+   package My::Schema;
+   use base qw/DBIx::Class::Schema/;
+   __PACKAGE__->default_resultset_attributes( { software_limit => 1 } );
+
 =head2 exception_action
 
 =over 4
@@ -787,13 +815,13 @@ sub populate {
 
 =item Arguments: @args
 
-=item Return Value: $new_schema
+=item Return Value: $self
 
 =back
 
 Similar to L</connect> except sets the storage object and connection
-data in-place on the Schema class. You should probably be calling
-L</connect> to get a proper Schema object instead.
+data B<in-place> on C<$self>. You should probably be calling
+L</connect> to get a properly L<cloned|/clone> Schema object instead.
 
 =head3 Overloading
 
@@ -918,6 +946,9 @@ sub compose_namespace {
   return $schema;
 }
 
+# LEGACY: The intra-call to this was removed in 66d9ef6b and then
+# the sub was de-documented way later in 249963d4. No way to be sure
+# nothing on darkpan is calling it directly, so keeping as-is
 sub setup_connection_class {
   my ($class, $target, @info) = @_;
   $class->inject_base($target => 'DBIx::Class::DB');