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.
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 first item provides a list of all possible values for the arguments of the method in order, separated by , , preceded by the text Arguments:
Example (for the belongs_to relationship):
The following possible argument sigils can be shown:
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.
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).
|o||The argument/return list is followed by a single paragraph describing what the method does.|
|o||The description paragraph is followed by another list. Each item in the list explains one of the possible argument/type combinations.|
The argument/return list is followed by some examples of how to use the
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 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.
This module is free software copyright by the DBIx::Class (DBIC) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class library.
|perl v5.20.3||DBIX::CLASS::MANUAL::READING (3)||2016-02-09|