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