1) changed all 4 space indentation to 2 space style indents for replication code...
[dbsrgits/DBIx-Class.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 it's name.
38
39 =item *
40
41 The header is followed by a one-item list.
42
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
45 text "Arguments: "
46
47 Example (for the belongs_to relationship):
48
49   =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
50
51 The following possible argument sigils can be shown:
52
53 =over
54
55 =item *
56
57 $var - A scalar (string or numeric) variable.
58
59 =item *
60
61 \%var - A variable containing reference to a hash.
62
63 =item *
64
65 \@var - A variable containing a reference to an array.
66
67 =item *
68
69 \$var - A variable containing a reference to a scalar variable.
70
71 =item *
72
73 ? - Optional, should be placed after the argument type and name.
74
75 =item *
76
77 | - Alternate argument types.
78
79 =back
80
81 NOTES:
82
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.
87
88 The C<?> for optional arguments always applies to the entire argument
89 value, not a particular type or argument.
90
91 =item *
92
93 The argument list is followed by a single paragraph describing what
94 the method does.
95
96 =item *
97
98 The description paragraph is followed by another list. Each item in
99 the list explains one of the possible argument/type combinations.
100
101 =item *
102
103 The argument list is followed by some examples of how to use the
104 method, using it's various types of arguments.
105
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.
110
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
113 calls.
114
115 The example should be followed by one or more paragraphs explaining
116 what it does.
117
118 Examples and explaining paragraphs can be repeated as necessary.
119
120 =back
121
122 =head1 AUTHORS
123
124 see L<DBIx::Class>
125
126 =head1 LICENSE
127
128 You may distribute this code under the same terms as Perl itself.
129
130 =cut
131
132
133