Add some subroutine docs. Must write another test so that I can understand all ins...

[dbsrgits/DBIx-Class-ResultSource-MultipleTableInheritance.git] / README

diff --git a/README b/README
index 8f0d469..ff755e0 100644 (file)
--- a/README
+++ b/README
@@ -63,9 +63,9 @@ SYNOPSIS
 
     Inherit from this package and you can make a resultset class from a
     view, but that's more than a little bit misleading: the result is
-    writable and updateable--transparently.
+    transparently writable.
 
-    This is accomplished through the use of stored functions that map
+    This is accomplished through the use of stored procedures that map
     changes written to the view to changes to the underlying concrete
     tables.
 
@@ -96,7 +96,7 @@ WHY?
                 has password
         }
 
-        class Investor isa User {
+        class Investor extends User {
             has dollars
         }
 
@@ -152,8 +152,9 @@ WHY?
 
 HOW?
     There is a third strategy implemented here. Make the database do more of
-    the work. It'll save us some typing and it'll make for more expressive
-    code. What if we could do this:
+    the work: hide the nasty bits so we don't have to handle them unless we
+    really want to. It'll save us some typing and it'll make for more
+    expressive code. What if we could do this:
 
         my $new_investor = $schema->resultset('Investor')->create(
             name => $args->{name},
@@ -161,11 +162,16 @@ HOW?
             dollars => $args->{dollars},
         );
 
-    And have it Just Work? The user ( {name => $args->{name}, password =>
-    $args->{password} } ) should be created transparently, and the use of
-    either user or investor in your code should require no special handling.
-    Deleting and updating $new_investor should also delete or update the
-    user row.
+    And have it Just Work? The user...
+
+        {
+            name => $args->{name},
+            password => $args->{password},
+        }
+
+    should be created behind the scenes, and the use of either user or
+    investor in your code should require no special handling. Deleting and
+    updating $new_investor should also delete or update the user row.
 
     It does. User and investor are both views, their concrete tables
     abstracted away behind a set of rules and triggers. You would expect the
@@ -189,6 +195,51 @@ HOW?
         DELETE FROM _investor_table WHERE ("id" = ?);
         DELETE FROM _user_table WHERE ("id" = ?);
 
+METHODS
+    new MTI find the parents, if any, of your resultset class and adds them
+        to the list of parent_sources for the table.
+
+    add_additional_parents
+        Continuing with coffee:
+
+            __PACKAGE__->result_source_instance->add_additional_parents(
+                qw/
+                    MyApp::Schema::Result::Beverage
+                    MyApp::Schema::Result::Liquid
+                /
+            );
+
+        This just lets you manually add additional parents beyond the ones
+        MTI finds.
+
+    add_additional_parent
+            __PACKAGE__->result_source_instance->add_additional_parent(
+                    MyApp::Schema::Result::Beverage
+            );
+
+        You can also add just one.
+
+    attach_additional_sources
+        MTI takes the parents' sources and relationships, creates new
+        DBIx::Class:Table object from them, and registers this as a new,
+        raw, source in the schema, e.g.,
+
+            use MyApp::Schema;
+
+            print STDERR map { "$_\n" } MyApp::Schema->sources;
+
+            # Coffee 
+            # Beverage
+            # Liquid
+            # Sumatra
+            # Raw::Sumatra
+
+        Raw::Sumatra will be used to generate the view.
+
+    view_definition
+        This takes the raw table and generates the view (and stored
+        procedures) you will use.
+
 AUTHOR
     Matt S. Trout, <mst@shadowcatsystems.co.uk>