4 DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
8 This doc should help users to understand how the examples and
9 documentation found in the L<DBIx::Class> distribution can be
12 Writers of DBIx::Class POD should also check here to make sure their
13 additions are consistent with the rest of the documentation.
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
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.
31 =head2 Method documentation
37 Each method starts with a "head2" statement of it's name.
41 The header is followed by a one-item list.
43 The single item provides a list of all possible values for the
44 arguments of the method in order, separated by C<, >, preceeded by the
47 Example (for the belongs_to relationship):
49 =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
51 The following possible argument sigils can be shown:
57 $var - A scalar (string or numeric) variable.
61 \%var - A variable containing reference to a hash.
65 \@var - A variable containing a reference to an array.
69 \$var - A variable containing a reference to a scalar variable.
73 ? - Optional, should be placed after the argument type and name.
77 | - Alternate argument types.
83 If several arguments are optional, it is always possible to pass
84 C<undef> as one optional argument in order to skip it and provide a
85 value for the following ones. This does not need to be indicated in
86 the Arguments line, it is assumed.
88 The C<?> for optional arguments always applies to the entire argument
89 value, not a particular type or argument.
93 The argument list is followed by a single paragraph describing what
98 The description paragraph is followed by another list. Each item in
99 the list explains one of the possible argument/type combinations.
103 The argument list is followed by some examples of how to use the
104 method, using it's various types of arguments.
106 The examples can also include ways to use the results if
107 applicable. For instance if the documentation is for a relationship
108 type, the examples can include how to call the resulting relation
109 accessor, how to use the relation name in a search and so on.
111 If some of the examples assume default values, these should be shown
112 with and without the actual arguments, with hints about the equivalent
115 The example should be followed by one or more paragraphs explaining
118 Examples and explaining paragraphs can be repeated as necessary.
128 You may distribute this code under the same terms as Perl itself.