[Bast-commits] r4429 - in DBIx-Class/0.08/trunk/lib/DBIx/Class: . Manual

[castaway at dev.catalyst.perl.org]

Author: castaway
Date: 2008-05-30 14:20:26 +0100 (Fri, 30 May 2008)
New Revision: 4429

Added:
   DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Reading.pod
Modified:
   DBIx-Class/0.08/trunk/lib/DBIx/Class/Relationship.pm
Log:
Started doc standards doc in Manual::Reading.
Fixed up belongs_to example to put more emphasis on the "column" part of "foreign_key_column" and corrected first paragraph.


Added: DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Reading.pod
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Reading.pod	                        (rev 0)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Reading.pod	2008-05-30 13:20:26 UTC (rev 4429)
@@ -0,0 +1,133 @@
+
+=head1 NAME
+
+DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
+
+=head1 DESCRIPTION
+
+This doc should help users to understand how the examples and
+documentation found in the L<DBIx::Class> distribution can be
+interpreted.
+
+Writers of DBIx::Class POD should also check here to make sure their
+additions are consistent with the rest of the documentation.
+
+=head1 METHODS
+
+Methods should be documented in the files which also contain the code
+for the method, or that file should be hidden from PAUSE completely,
+in which case the methods are documented in the file which loads
+it. Methods may also be documented and refered to in files
+representing the major objects or components on which they can be
+called.
+
+For example, L<DBIx::Class::Relationship> documents the methods
+actually coded in the helper relationship classes like
+DBIx::Class::Relationship::BelongsTo. The BelongsTo file itself is
+hidden from pause as it has no documentation. The accessors created by
+relationships should be mentioned in L<DBIx::Class::Row>, the major
+object that they will be called on.
+
+=head2 Method documentation
+
+=over
+
+=item *
+
+Each method starts with a "head2" statement of it's name.
+
+=item *
+
+The header is followed by a one-item list.
+
+The single item provides a list of all possible values for the
+arguments of the method in order, separated by C<, >, preceeded by the
+text "Arguments: "
+
+Example (for the belongs_to relationship):
+
+  =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
+
+The following possible argument sigils can be shown:
+
+=over
+
+=item *
+
+$var - A scalar (string or numeric) variable.
+
+=item *
+
+\%var - A variable containing reference to a hash.
+
+=item *
+
+\@var - A variable containing a reference to an array.
+
+=item *
+
+\$var - A variable containing a reference to a scalar variable.
+
+=item *
+
+? - Optional, should be placed after the argument type and name.
+
+=item *
+
+| - Alternate argument types.
+
+=back
+
+NOTES:
+
+If several arguments are optional, it is always possible to pass
+C<undef> as one optional argument in order to skip it and provide a
+value for the following ones. This does not need to be indicated in
+the Arguments line, it is assumed.
+
+The C<?> for optional arguments always applies to the entire argument
+value, not a particular type or argument.
+
+=item *
+
+The argument list is followed by a single paragraph describing what
+the method does.
+
+=item *
+
+The description paragraph is followed by another list. Each item in
+the list explains one of the possible argument/type combinations.
+
+=item *
+
+The argument list is followed by some examples of how to use the
+method, using it's various types of arguments.
+
+The examples can also include ways to use the results if
+applicable. For instance if the documentation is for a relationship
+type, the examples can include how to call the resulting relation
+accessor, how to use the relation name in a search and so on.
+
+If some of the examples assume default values, these should be shown
+with and without the actual arguments, with hints about the equivalent
+calls.
+
+The example should be followed by one or more paragraphs explaining
+what it does.
+
+Examples and explaining paragraphs can be repeated as necessary.
+
+=back
+
+=head1 AUTHORS
+
+see L<DBIx::Class>
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.
+
+=cut
+
+
+

Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/Relationship.pm
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/Relationship.pm	2008-05-30 12:36:19 UTC (rev 4428)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/Relationship.pm	2008-05-30 13:20:26 UTC (rev 4429)
@@ -98,29 +98,30 @@
 
 =head1 METHODS
 
-All helper methods take the following arguments:
+All helper methods are called similar to the following template:
 
-  __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>.
 
-See L<DBIx::Class::Relationship::Base> for a list of valid attributes and valid
-relationship attributes.
+See L<DBIx::Class::Relationship::Base> for documentation on the
+attrubutes that are allowed in the C<$attrs> argument.
 
+
 =head2 belongs_to
 
 =over 4
 
-=item Arguments: $accessor_name, $related_class, $foreign_key_column|$cond?, $attr?
+=item Arguments: $accessor_name, $related_class, $fk_column|$cond?, $attr?
 
 =back
 
 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.
+join, unless C<$fk_column> specifies the foreign key column in
+this class or C<$cond> specifies a reference to a join condition hash.
 
 =over
 
@@ -128,9 +129,10 @@
 
 This argument is the name of the method you can call on a
 L<DBIx::Class::Row> object to retrieve the instance of the foreign
-class matching this relationship.
+class matching this relationship. This is often called the
+C<relation(ship) name>.
 
-Use this accessor_name (relation name) in L<DBIx::Class::ResultSet/join>
+Use this accessor_name in L<DBIx::Class::ResultSet/join>
 or L<DBIx::Class::ResultSet/prefetch> to join to the foreign table
 indicated by this relationship.
 
@@ -139,7 +141,7 @@
 This is the class name of the table referenced by the foreign key in
 this class.
 
-=item foreign_key_column
+=item fk_column
 
 The column name on this class that contains the foreign key.