1DBIx::Class::Manual::ReUasdeirngC(o3n)tributed Perl DocuDmBeInxt:a:tCiloanss::Manual::Reading(3)
2
3
4

NAME

6       DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
7

DESCRIPTION

9       This doc should help users to understand how the examples and
10       documentation found in the DBIx::Class distribution can be 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

METHODS

16       Methods should be documented in the files which also contain the code
17       for the method, or that file should be hidden from PAUSE completely, in
18       which case the methods are documented in the file which loads it.
19       Methods may also be documented and referred to in files representing
20       the major objects or components on which they can be called.
21
22       For example, DBIx::Class::Relationship documents the methods actually
23       coded in the helper relationship classes like
24       DBIx::Class::Relationship::BelongsTo. The BelongsTo file itself is
25       hidden from PAUSE as it has no documentation. The accessors created by
26       relationships should be mentioned in DBIx::Class::Row, the major object
27       that they will be called on.
28
29   Method documentation
30       •   Each method starts with a "head2" statement of its name.
31
32           Just the plain method name, not an example of how to call it, or a
33           link.  This is to ensure easy linking to method documentation from
34           other POD.
35
36       •   The header is followed by a two-item list. This contains a
37           description of the arguments the method is expected to take, and an
38           indication of what the method returns.
39
40           The first item provides a list of all possible values for the
41           arguments of the method in order, separated by ", ", preceded by
42           the text "Arguments: "
43
44           Example (for the belongs_to relationship):
45
46             =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?
47
48           The following possible argument sigils can be shown:
49
50           •   $var - A scalar (string or numeric) variable.
51
52           •   \%var - A variable containing reference to a hash.
53
54           •   \@var - A variable containing a reference to an array.
55
56           •   \$var - A variable containing a reference to a scalar variable.
57
58           •   %var - A hashref variable (list of key/value pairs) - rarely
59               used in DBIx::Class.
60
61               Reading an argument as a hash variable will consume all
62               subsequent method arguments, use with caution.
63
64           •   @var - An array variable (list of values).
65
66               Reading an argument as a array variable will consume all
67               subsequent method arguments, use with caution.
68
69           •   $obj - Reference to the source class or object definition
70
71               All arguments and return values should provide a link to the
72               object's class documentation or definition, even if it's the
73               same class as the current documentation.  For example:
74
75                 ## Correct, if stated within DBIx::Class::ResultSet
76                 L<$resultset|/new>
77
78                 ## Correct, if stated outside DBIx::Class::ResultSet
79                 L<$resultset|DBIx::Class::ResultSet>
80
81           •   ? - Optional, should be placed after the argument type and
82               name.
83
84                 ## Correct
85                 \%myhashref|\@myarrayref?
86
87                 ## Wrong
88                 \%myhashref?|\@myarrayref
89
90               Applies to the entire argument.
91
92               Optional arguments can be left out of method calls, unless the
93               caller needs to pass in any of the following arguments. In
94               which case the caller should pass "undef" in place of the
95               missing argument.
96
97           •   | - Alternate argument content types.
98
99               At least one of these must be supplied unless the argument is
100               also marked optional.
101
102           The second item starts with the text "Return Value:". The remainder
103           of the line is either the text "not defined" or a variable with a
104           descriptive name.
105
106             ## Good examples
107             =item Return Value: not defined
108             =item Return Value: L<$schema|DBIx::Class::Schema>
109             =item Return Value: $classname
110
111             ## Bad examples
112             =item Return Value: The names
113
114           "not defined" means the method does not deliberately return a
115           value, and the caller should not use or rely on anything it does
116           return.  (Perl functions always return something, usually the
117           result of the last code statement, if there is no explicit return
118           statement.)  This is different than specifying "undef", which means
119           that it explicitly returns undef, though usually this is used an
120           alternate return (like "$obj | undef").
121
122       •   The argument/return list is followed by a single paragraph
123           describing what the method does.
124
125       •   The description paragraph is followed by another list. Each item in
126           the list explains one of the possible argument/type combinations.
127
128           This list may be omitted if the author feels that the variable
129           names are self-explanatory enough to not require it. Use best
130           judgement.
131
132       •   The argument/return list is followed by some examples of how to use
133           the method, using its various types of arguments.
134
135           The examples can also include ways to use the results if
136           applicable. For instance, if the documentation is for a
137           relationship type, the examples can include how to call the
138           resulting relation accessor, how to use the relation name in a
139           search and so on.
140
141           If some of the examples assume default values, these should be
142           shown with and without the actual arguments, with hints about the
143           equivalent calls.
144
145           The example should be followed by one or more paragraphs explaining
146           what it does.
147
148           Examples and explaining paragraphs can be repeated as necessary.
149

FURTHER QUESTIONS?

151       Check the list of additional DBIC resources.
152

154       This module is free software copyright by the DBIx::Class (DBIC)
155       authors. You can redistribute it and/or modify it under the same terms
156       as the DBIx::Class library.
157
158
159
160perl v5.34.0                      2022-01-21   DBIx::Class::Manual::Reading(3)
Impressum