better explanation for optional fk values in rels

diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm
index 26a07ef..8098342 100644 (file)
--- a/lib/DBIx/Class/Relationship.pm
+++ b/lib/DBIx/Class/Relationship.pm
@@ -192,14 +192,14 @@ more info see L<DBIx::Class::Relationship::Base/condition>.
   $book->get_column('author_id');
 
 
-If the relationship is optional -- i.e. the column containing the
-foreign key can be NULL -- then the belongs_to relationship does the
+If the the column containin the foreign key of a relationship
+can be NULL the belongs_to relationship still does the
 right thing. Thus, in the example above C<< $obj->author >> would
-return C<undef>.  However in this case you would probably want to set
-the L<join_type|DBIx::Class::Relationship::Base/join_type> attribute so that
-a C<LEFT JOIN> is done, which makes complex resultsets involving
-C<join> or C<prefetch> operations work correctly.  The modified
-declaration is shown below:
+return C<undef>. However you probably want to set the
+L<join_type|DBIx::Class::Relationship::Base/join_type> attribute so that
+a C<LEFT JOIN> is done, which makes relationship traversal in complex
+resultsets work correctly. (i.e. resultsets involving C<join> or
+C<prefetch> operations). The modified declaration is shown below:
 
   # in a Book class (where Author has_many Books)
   __PACKAGE__->belongs_to(
@@ -209,7 +209,6 @@ declaration is shown below:
     { join_type => 'left' }
   );
 
-
 Cascading deletes are off by default on a C<belongs_to>
 relationship. To turn them on, pass C<< cascade_delete => 1 >>
 in the $attr hashref.