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
+it. Methods may also be documented and referred 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
+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.
=item *
-Each method starts with a "head2" statement of it's name.
+Each method starts with a "head2" statement of its name.
+
+Just the plain method name, not an example of how to call it, or a link.
+This is to ensure easy linking to method documentation from other POD.
=item *
-The header is followed by a one-item list.
+The header is followed by a two-item list. This contains a description
+of the arguments the method is expected to take, and an indication of
+what the method returns.
-The single item provides a list of all possible values for the
-arguments of the method in order, separated by C<, >, preceeded by the
+The first item provides a list of all possible values for the
+arguments of the method in order, separated by C<, >, preceded by the
text "Arguments: "
Example (for the belongs_to relationship):
=item *
+%var - A hashref variable (list of key/value pairs) - rarely used in DBIx::Class.
+
+Reading an argument as a hash variable will consume all subsequent
+method arguments, use with caution.
+
+=item *
+
+@var - An array variable (list of values).
+
+Reading an argument as a array variable will consume all subsequent
+method arguments, use with caution.
+
+=item *
+
? - Optional, should be placed after the argument type and name.
+ ## Correct
+ \%myhashref|\@myarrayref?
+
+ ## Wrong
+ \%myhashref?|\@myarrayref
+
+Applies to the entire argument.
+
+Optional arguments can be left out of method calls, unless the caller
+needs to pass in any of the following arguments. In which case the
+caller should pass C<undef> in place of the missing argument.
+
=item *
-| - Alternate argument types.
+| - Alternate argument content types.
+
+At least one of these must be supplied unless the argument is also
+marked optional.
=back
-NOTES:
+The second item starts with the text "Return value:". The remainder of
+the line is either the text "undefined", a text describing the result of
+the method, or a variable with a descriptive name.
+
+ ## Good examples
+ =item Return value: undefined
+ =item Return value: A schema object
+ =item Return value: $classname
-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.
+ ## Bad examples
+ =item Return value: The names
-The C<?> for optional arguments always applies to the entire argument
-value, not a particular type or argument.
+"undefined" means the method does not deliberately return a value, and
+the caller should not use or rely on anything it does return. (Perl
+functions always return something, usually the result of the last code
+statement, if there is no explicit return statement.)
=item *
The description paragraph is followed by another list. Each item in
the list explains one of the possible argument/type combinations.
+This list may be omitted if the author feels that the variable names are
+self-explanatory enough to not require it. Use best judgement.
+
=item *
The argument list is followed by some examples of how to use the
-method, using it's various types of arguments.
+method, using its 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
+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.
=back
-=head1 AUTHORS
+=head1 AUTHOR AND CONTRIBUTORS
-see L<DBIx::Class>
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
=head1 LICENSE
You may distribute this code under the same terms as Perl itself.
=cut
-
-
-
projects / dbsrgits/DBIx-Class.git / blobdiff