Tiny POD formatting fix
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Reading.pod
CommitLineData
8457faf7 1
2=head1 NAME
3
4DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
5
6=head1 DESCRIPTION
7
8This doc should help users to understand how the examples and
9documentation found in the L<DBIx::Class> distribution can be
10interpreted.
11
12Writers of DBIx::Class POD should also check here to make sure their
13additions are consistent with the rest of the documentation.
14
15=head1 METHODS
16
17Methods should be documented in the files which also contain the code
18for the method, or that file should be hidden from PAUSE completely,
19in which case the methods are documented in the file which loads
20it. Methods may also be documented and refered to in files
21representing the major objects or components on which they can be
22called.
23
24For example, L<DBIx::Class::Relationship> documents the methods
25actually coded in the helper relationship classes like
26DBIx::Class::Relationship::BelongsTo. The BelongsTo file itself is
27hidden from pause as it has no documentation. The accessors created by
28relationships should be mentioned in L<DBIx::Class::Row>, the major
29object that they will be called on.
30
31=head2 Method documentation
32
33=over
34
35=item *
36
a4a1ad10 37Each method starts with a "head2" statement of its name.
38
39Just the plain method name, not an example of how to call it, or a link.
40This is to ensure easy linking to method documentation from other POD.
8457faf7 41
42=item *
43
a4a1ad10 44The header is followed by a two-item list. This contains a description
45of the arguments the method is expected to take, and an indication of
46what the method returns.
8457faf7 47
a4a1ad10 48The first item provides a list of all possible values for the
8457faf7 49arguments of the method in order, separated by C<, >, preceeded by the
50text "Arguments: "
51
52Example (for the belongs_to relationship):
53
54 =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
55
56The following possible argument sigils can be shown:
57
58=over
59
60=item *
61
62$var - A scalar (string or numeric) variable.
63
64=item *
65
66\%var - A variable containing reference to a hash.
67
68=item *
69
70\@var - A variable containing a reference to an array.
71
72=item *
73
74\$var - A variable containing a reference to a scalar variable.
75
76=item *
77
a4a1ad10 78%var - A hashref variable (list of key/value pairs) - rarely used in DBIx::Class.
79
80Reading an argument as a hash variable will consume all subsequent
81method arguments, use with caution.
82
83=item *
84
85@var - An array variable (list of values).
86
87Reading an argument as a array variable will consume all subsequent
88method arguments, use with caution.
89
90=item *
91
8457faf7 92? - Optional, should be placed after the argument type and name.
93
a4a1ad10 94 ## Correct
95 \%myhashref|\@myarrayref?
96
97 ## Wrong
98 \%myhashref?|\@myarrayref
99
100Applies to the entire argument.
101
102Optional arguments can be left out of method calls, unless the caller
103needs to pass in any of the following arguments. In which case the
104caller should pass C<undef> in place of the missing argument.
105
8457faf7 106=item *
107
a4a1ad10 108| - Alternate argument content types.
109
110At least one of these must be supplied unless the argument is also
111marked optional.
8457faf7 112
113=back
114
a4a1ad10 115The second item starts with the text "Return value:". The remainder of
116the line is either the text "undefined", a text describing the result of
117the method, or a variable with a descriptive name.
8457faf7 118
a4a1ad10 119 ## Good examples
120 =item Return value: undefined
121 =item Return value: A schema object
122 =item Return value: $classname
8457faf7 123
a4a1ad10 124 ## Bad examples
125 =item Return value: The names
126
127"undefined" means the method does not deliberately return a value, and
128the caller should not use or rely on anything it does return. (Perl
129functions always return something, usually the result of the last code
130statement, if there is no explicit return statement.)
8457faf7 131
132=item *
133
134The argument list is followed by a single paragraph describing what
135the method does.
136
137=item *
138
139The description paragraph is followed by another list. Each item in
140the list explains one of the possible argument/type combinations.
141
a4a1ad10 142This list may be omitted if the author feels that the variable names are
143self-explanatory enough to not require it. Use best judgement.
144
8457faf7 145=item *
146
147The argument list is followed by some examples of how to use the
148method, using it's various types of arguments.
149
150The examples can also include ways to use the results if
151applicable. For instance if the documentation is for a relationship
152type, the examples can include how to call the resulting relation
153accessor, how to use the relation name in a search and so on.
154
155If some of the examples assume default values, these should be shown
156with and without the actual arguments, with hints about the equivalent
157calls.
158
159The example should be followed by one or more paragraphs explaining
160what it does.
161
162Examples and explaining paragraphs can be repeated as necessary.
163
164=back
165
166=head1 AUTHORS
167
168see L<DBIx::Class>
169
170=head1 LICENSE
171
172You may distribute this code under the same terms as Perl itself.
173
174=cut
175
176
177