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 referred 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 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.
  41
  42 =item *
  43
  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.
  47
  48 The first item provides a list of all possible values for the
  49 arguments of the method in order, separated by C<, >, preceded by the
  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
  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
  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
 106 ? - Optional, should be placed after the argument type and name.
 107
 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
 120 =item *
 121
 122 | - Alternate argument content types.
 123
 124 At least one of these must be supplied unless the argument is also
 125 marked optional.
 126
 127 =back
 128
 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.
 132
 133   ## Good examples
 134   =item Return Value: not defined
 135   =item Return Value: L<$schema|DBIx::Class::Schema>
 136   =item Return Value: $classname
 137
 138   ## Bad examples
 139   =item Return Value: The names
 140
 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
 143 functions always return something, usually the result of the last code
 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>).
 147
 148 =item *
 149
 150 The argument/return list is followed by a single paragraph describing what
 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
 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
 161 =item *
 162
 163 The argument/return list is followed by some examples of how to use the
 164 method, using its various types of arguments.
 165
 166 The examples can also include ways to use the results if
 167 applicable. For instance, if the documentation is for a relationship
 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
 182 =head1 AUTHOR AND CONTRIBUTORS
 183
 184 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
 185
 186 =head1 LICENSE
 187
 188 You may distribute this code under the same terms as Perl itself.
 189
 190 =cut