DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
This doc should help users to understand how the examples and documentation found in the 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.
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 referred to in files representing the major objects or components on which they can be called.
For example, 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 DBIx::Class::Row, the major object that they will be called on.
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.
The first item provides a list of all possible values for the arguments of the method in order,
preceded 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:
Reading an argument as a hash variable will consume all subsequent method arguments, use with caution.
Reading an argument as a array variable will consume all subsequent method arguments, use with caution.
All arguments and return values should provide a link to the object's class documentation or definition, even if it's the same class as the current documentation. For example:
## Correct, if stated within DBIx::Class::ResultSet L<$resultset|/new> ## Correct, if stated outside DBIx::Class::ResultSet L<$resultset|DBIx::Class::ResultSet>
## 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
undef in place of the missing argument.
At least one of these must be supplied unless the argument is also marked optional.
The second item starts with the text "Return Value:". The remainder of the line is either the text "not defined" or a variable with a descriptive name.
## Good examples =item Return Value: not defined =item Return Value: L<$schema|DBIx::Class::Schema> =item Return Value: $classname ## Bad examples =item Return Value: The names
"not defined" 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.) This is different than specifying "undef", which means that it explicitly returns undef, though usually this is used an alternate return (like
$obj | undef).
This list may be omitted if the author feels that the variable names are self-explanatory enough to not require it. Use best judgement.
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.
Check the list of additional DBIC resources.