described schema better, and added note about when you want to use it

in the intro.

diff --git a/lib/DBIx/Class/Manual/Intro.pod b/lib/DBIx/Class/Manual/Intro.pod
index 158f2bc..10cb50e 100644 (file)
--- a/lib/DBIx/Class/Manual/Intro.pod
+++ b/lib/DBIx/Class/Manual/Intro.pod
@@ -20,7 +20,8 @@ like this:
 You will also want to load some of L<DBIx::Class>'s components. 
 L<DBIx::Class::Core>  provides a good basic set. In addition you'll
 have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB> We'll
-use DB in this introduction, since it involves less magic.
+use DB in this introduction, since it involves less magic. Schema is 
+mostly useful if you want to use multiple database connections.
 
   __PACKAGE__->load_components(qw/Core DB/);
 

diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 72c1583..eb3246c 100644 (file)
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -44,6 +44,11 @@ DBIx::Class::Schema - composable schemas
 
 =head1 DESCRIPTION
 
+Creates database classes based on a schema. This allows you to have more than
+one concurrent connection using the same database classes, by making 
+subclasses under a new namespace for each connection. If you only need one 
+class, you should probably use L<DBIx::Class::DB> directly instead.
+
 =head1 METHODS
 
 =over 4
@@ -51,7 +56,7 @@ DBIx::Class::Schema - composable schemas
 =item register_class <component> <component_class>
 
 Registers the class in the schema's class_registrations. This is a hash
-containing components, and their representative classes. It's used by
+containing database classes, keyed by their monikers. It's used by
 compose_connection to create/modify all the existing database classes.
 
 =cut
@@ -77,9 +82,9 @@ sub registered_classes {
 
 =item  load_classes [<classes>}
 
-Uses L<Module::Find> to find all components, unless specified explicitly.
-Then it loads the component (using L<use>), and registers them (using 
-B<register_class>
+Uses L<Module::Find> to find all classes under the database class' namespace,
+or uses the classes you select.  Then it loads the component (using L<use>), 
+and registers them (using B<register_class>);
 
 =cut
 
@@ -100,7 +105,12 @@ sub load_classes {
   }
 }
 
-=item compose_connection
+=item compose_connection <target> <@db_info>
+
+This is the most important method in this class. it takes a target namespace,
+as well as dbh connection info, and creates a L<DBIx::Class::DB> class as
+well as subclasses for each of your database classes in this namespace, using
+this connection.
 
 =cut
 
@@ -131,6 +141,9 @@ sub compose_connection {
 
 =item setup_connection_class <$target> <@info>
 
+Sets up a database connection class to inject between the schema
+and the subclasses the schema creates.
+
 =cut
 
 sub setup_connection_class {