Commit | Line | Data |
8457faf7 |
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 |
48580715 |
20 | it. Methods may also be documented and referred to in files |
8457faf7 |
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 |
48580715 |
27 | hidden from PAUSE as it has no documentation. The accessors created by |
8457faf7 |
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 | |
a4a1ad10 |
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. |
8457faf7 |
41 | |
42 | =item * |
43 | |
a4a1ad10 |
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. |
8457faf7 |
47 | |
a4a1ad10 |
48 | The first item provides a list of all possible values for the |
c1300297 |
49 | arguments of the method in order, separated by C<, >, preceded by the |
8457faf7 |
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 | |
a4a1ad10 |
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 | |
fb13a49f |
92 | L<$obj|DBIx::Class> - Reference to the source class or object definition |
93 | |
94 | All arguments and return values should provide a link to the object's |
95 | class documentation or definition, even if it's the same class as the current |
96 | documentation. For example: |
97 | |
98 | ## Correct, if stated within DBIx::Class::ResultSet |
99 | L<$resultset|/new> |
100 | |
101 | ## Correct, if stated outside DBIx::Class::ResultSet |
102 | L<$resultset|DBIx::Class::ResultSet> |
103 | |
104 | =item * |
105 | |
8457faf7 |
106 | ? - Optional, should be placed after the argument type and name. |
107 | |
a4a1ad10 |
108 | ## Correct |
109 | \%myhashref|\@myarrayref? |
110 | |
111 | ## Wrong |
112 | \%myhashref?|\@myarrayref |
113 | |
114 | Applies to the entire argument. |
115 | |
116 | Optional arguments can be left out of method calls, unless the caller |
117 | needs to pass in any of the following arguments. In which case the |
118 | caller should pass C<undef> in place of the missing argument. |
119 | |
8457faf7 |
120 | =item * |
121 | |
8273e845 |
122 | | - Alternate argument content types. |
a4a1ad10 |
123 | |
124 | At least one of these must be supplied unless the argument is also |
125 | marked optional. |
8457faf7 |
126 | |
127 | =back |
128 | |
fb13a49f |
129 | The second item starts with the text "Return Value:". The remainder of |
130 | the line is either the text "not defined" or a variable with a descriptive |
131 | name. |
8457faf7 |
132 | |
a4a1ad10 |
133 | ## Good examples |
fb13a49f |
134 | =item Return Value: not defined |
135 | =item Return Value: L<$schema|DBIx::Class::Schema> |
136 | =item Return Value: $classname |
8457faf7 |
137 | |
a4a1ad10 |
138 | ## Bad examples |
fb13a49f |
139 | =item Return Value: The names |
a4a1ad10 |
140 | |
fb13a49f |
141 | "not defined" means the method does not deliberately return a value, and |
142 | the caller should not use or rely on anything it does return. (Perl |
a4a1ad10 |
143 | functions always return something, usually the result of the last code |
fb13a49f |
144 | statement, if there is no explicit return statement.) This is different |
145 | than specifying "undef", which means that it explicitly returns undef, |
146 | though usually this is used an alternate return (like C<$obj | undef>). |
8457faf7 |
147 | |
148 | =item * |
149 | |
fb13a49f |
150 | The argument/return list is followed by a single paragraph describing what |
8457faf7 |
151 | the method does. |
152 | |
153 | =item * |
154 | |
155 | The description paragraph is followed by another list. Each item in |
156 | the list explains one of the possible argument/type combinations. |
157 | |
a4a1ad10 |
158 | This list may be omitted if the author feels that the variable names are |
159 | self-explanatory enough to not require it. Use best judgement. |
160 | |
8457faf7 |
161 | =item * |
162 | |
fb13a49f |
163 | The argument/return list is followed by some examples of how to use the |
48580715 |
164 | method, using its various types of arguments. |
8457faf7 |
165 | |
166 | The examples can also include ways to use the results if |
48580715 |
167 | applicable. For instance, if the documentation is for a relationship |
8457faf7 |
168 | type, the examples can include how to call the resulting relation |
169 | accessor, how to use the relation name in a search and so on. |
170 | |
171 | If some of the examples assume default values, these should be shown |
172 | with and without the actual arguments, with hints about the equivalent |
173 | calls. |
174 | |
175 | The example should be followed by one or more paragraphs explaining |
176 | what it does. |
177 | |
178 | Examples and explaining paragraphs can be repeated as necessary. |
179 | |
180 | =back |
181 | |
0c11ad0e |
182 | =head1 AUTHOR AND CONTRIBUTORS |
8457faf7 |
183 | |
0c11ad0e |
184 | See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class |
8457faf7 |
185 | |
186 | =head1 LICENSE |
187 | |
188 | You may distribute this code under the same terms as Perl itself. |
189 | |
190 | =cut |