From: Jess Robinson Date: Fri, 30 May 2008 13:20:26 +0000 (+0000) Subject: Started doc standards doc in Manual::Reading. X-Git-Tag: v0.08240~443 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=dbsrgits%2FDBIx-Class.git;a=commitdiff_plain;h=8457faf7d3ab7484b4da1f0a68d3b0231e7d21bf 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. --- diff --git a/lib/DBIx/Class/Manual/Reading.pod b/lib/DBIx/Class/Manual/Reading.pod new file mode 100644 index 0000000..6aa4830 --- /dev/null +++ b/lib/DBIx/Class/Manual/Reading.pod @@ -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 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 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, 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 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 + +=head1 LICENSE + +You may distribute this code under the same terms as Perl itself. + +=cut + + + diff --git a/lib/DBIx/Class/Relationship.pm b/lib/DBIx/Class/Relationship.pm index 4dee96b..8dbf96a 100644 --- a/lib/DBIx/Class/Relationship.pm +++ b/lib/DBIx/Class/Relationship.pm @@ -98,29 +98,30 @@ L. =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 for C<$cond> if you want to use the default value for it, but still want to set C<$attrs>. -See L for a list of valid attributes and valid -relationship attributes. +See L 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 @@ C<$related_class> or C<$cond> specifies a reference to a join condition hash. This argument is the name of the method you can call on a L object to retrieve the instance of the foreign -class matching this relationship. +class matching this relationship. This is often called the +C. -Use this accessor_name (relation name) in L +Use this accessor_name in L or L to join to the foreign table indicated by this relationship. @@ -139,7 +141,7 @@ indicated by this relationship. 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.