[Dbix-class] DBIC::Relationship.pm doc nits patch

[Thomas L. Shinnick]

This patch fixes a couple small formatting glitches, plus two errors 
In the pod for Relationship.pm.

In three spots the join condition column names were wrong, e.g.
        My::DBIC::Schema::Author->has_many( books => 
'My::DBIC::Schema::Book', {
     -    'foreign.author' => 'self.author',
     +    'foreign.author' => 'self.id',
        });

And in the description for belongs_to() the foreign key was 
mistakenly identified as being in the "related class".  Unlike the 
other relationships, the key described for belongs_to() is in the 
"calling class".

I saw _somewhere_ a nice cheatsheet for "what that dang third 
argument could be".  And I know it has come up on the maillist.  The 
constant description is that the third argument is always the 
"foreign key column name" (unless it is a join condition).  But it is 
darn hard to remember who/to/from/where correctly each time.

   has_many
   might_have
   has_one
       the foreign key column name in the *other* table that 
references the primary key of *this* table

   belongs_to
       the foreign key column name in *this* table that references 
the primary key of the *other* table
-------------- next part --------------
--- Relationship.pm.rev_2802	Sat Sep 30 21:39:07 2006
+++ Relationship.pm	Sat Sep 30 23:14:44 2006
@@ -23,6 +23,7 @@
                                 'actor');
   MyDB::Schema::Role->has_many('actorroles' => 'MyDB::Schema::ActorRole',
                                 'role');
+
   MyDB::Schema::ActorRole->belongs_to('role' => 'MyDB::Schema::Role');
   MyDB::Schema::ActorRole->belongs_to('actor' => 'MyDB::Schema::Actor');
 
@@ -60,6 +61,7 @@
 
  my $fred = $schema->resultset('Author')->find({ Name => 'Fred' });
  my $fredsbooks = $schema->resultset('Book')->search({ Author => $fred->ID });
+
 With a has_many relationship called "books" on Author (see below for details),
 we can do this instead:
 
@@ -69,9 +71,9 @@
 L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
 of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
 the relationships can be searched using the "search_related" method.
-In list context, each returns a list of Row objects for the related class,
+In list context, each call returns a list of Row objects for the related class,
 in scalar context, a new ResultSet representing the joined tables is
-returned. Thus, the calls can be chained to produce complex queries.
+returned. Thus the calls can be chained to produce complex queries.
 Since the database is not actually queried until you attempt to retrieve
 the data for an actual item, no time is wasted producing them.
 
@@ -99,8 +101,8 @@
 
 All helper methods take the following arguments:
 
-  __PACKAGE__>$method_name('relname', 'Foreign::Class', $cond, $attrs);
-  
+  __PACKAGE__->$method_name('relname', 'Foreign::Class', $cond, $attrs);
+
 Both C<$cond> and C<$attrs> are optional. Pass C<undef> for C<$cond> if
 you want to use the default value for it, but still want to set C<$attrs>.
 
@@ -121,17 +123,23 @@
   my $author_obj = $obj->author; # get author object
   $obj->author( $new_author_obj ); # set author object
 
-The above belongs_to relationship could also have been specified as,
+The above belongs_to relationship defaults to the same as 
 
-  My::DBIC::Schema::Book->belongs_to( author,
-                                      'My::DBIC::Schema::Author',
-                                      { 'self.author' => 'foreign.author' } );
-
-Creates a relationship where the calling class stores the foreign class's
-primary key in one (or more) of its columns. This relationship defaults to
-using C<$accessor_name> as the foreign key in C<$related_class> to resolve the
-join, unless C<$foreign_key_column> specifies the foreign key column in
-C<$related_class> or C<$cond> specifies a reference to a join condition hash.
+  My::DBIC::Schema::Book->belongs_to( 'author' => 'My::DBIC::Schema::Author',
+                                      'author' );
+
+or to explicitly describe the join relationship could have been written
+
+  My::DBIC::Schema::Book->belongs_to( 'author' => 'My::DBIC::Schema::Author',
+                                      { 'foreign.id' => 'self.author' } );
+
+Creates a relationship description where this class stores the foreign class's
+primary key value in one (or more) of its columns.  If the third argument
+isn't specified, then C<$accessor_name> will be used as the default column
+name for this classes' foreign key value.  The third argument can be used to
+specify the foreign key column name as C<$foreign_key_column>, when the
+accessor name doesn't match the table column name.  Finally, the third
+argument C<$cond> can specify the full join condition hash.
 
 If the relationship is optional -- i.e. the column containing the foreign key
 can be NULL -- then the belongs_to relationship does the right thing. Thus, in
@@ -181,7 +189,7 @@
 explicit join condition:
 
   My::DBIC::Schema::Author->has_many( books => 'My::DBIC::Schema::Book', {
-    'foreign.author' => 'self.author',
+    'foreign.author' => 'self.id',
   });
 
 Creates a one-to-many relationship, where the corresponding elements of the
@@ -232,9 +240,7 @@
 
   My::DBIC::Schema::Author->might_have( pseudonym =>
                                         'My::DBIC::Schema::Pseudonym',
-                                        { 'foreign.author' => 'self.author' } );
-
-Assuming the Pseudonym table has
+                                        { 'foreign.author' => 'self.id' } );
 
 Creates an optional one-to-one relationship with a class. This relationship
 defaults to using C<$accessor_name> as the foreign key in C<$related_class> to