[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Reading.pod


=head1 NAME

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

=head1 DESCRIPTION

This doc should help users to understand how the examples and
documentation found in the L<DBIx::Class> distribution can be
interpreted.

Writers of DBIx::Class POD should also check here to make sure their
additions are consistent with the rest of the documentation.

=head1 METHODS

Methods should be documented in the files which also contain the code
for the method, or that file should be hidden from PAUSE completely,
in which case the methods are documented in the file which loads
it. Methods may also be documented and refered to in files
representing the major objects or components on which they can be
called.

For example, L<DBIx::Class::Relationship> documents the methods
actually coded in the helper relationship classes like
DBIx::Class::Relationship::BelongsTo. The BelongsTo file itself is
hidden from pause as it has no documentation. The accessors created by
relationships should be mentioned in L<DBIx::Class::Row>, the major
object that they will be called on.

=head2 Method documentation

=over

=item *

Each method starts with a "head2" statement of it's name.

=item *

The header is followed by a one-item list.

The single item provides a list of all possible values for the
arguments of the method in order, separated by C<, >, preceeded by the
text "Arguments: "

Example (for the belongs_to relationship):

  =item Arguments: $accessor_name, $related_class, $fk_column|\%cond|\@cond?, \%attr?

The following possible argument sigils can be shown:

=over

=item *

$var - A scalar (string or numeric) variable.

=item *

\%var - A variable containing reference to a hash.

=item *

\@var - A variable containing a reference to an array.

=item *

\$var - A variable containing a reference to a scalar variable.

=item *

? - Optional, should be placed after the argument type and name.

=item *

| - Alternate argument types.

=back

NOTES:

If several arguments are optional, it is always possible to pass
C<undef> as one optional argument in order to skip it and provide a
value for the following ones. This does not need to be indicated in
the Arguments line, it is assumed.

The C<?> for optional arguments always applies to the entire argument
value, not a particular type or argument.

=item *

The argument list is followed by a single paragraph describing what
the method does.

=item *

The description paragraph is followed by another list. Each item in
the list explains one of the possible argument/type combinations.

=item *

The argument list is followed by some examples of how to use the
method, using it's various types of arguments.

The examples can also include ways to use the results if
applicable. For instance if the documentation is for a relationship
type, the examples can include how to call the resulting relation
accessor, how to use the relation name in a search and so on.

If some of the examples assume default values, these should be shown
with and without the actual arguments, with hints about the equivalent
calls.

The example should be followed by one or more paragraphs explaining
what it does.

Examples and explaining paragraphs can be repeated as necessary.

=back

=head1 AUTHORS

see L<DBIx::Class>

=head1 LICENSE

You may distribute this code under the same terms as Perl itself.

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