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