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 |
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 | |