point out where in the docs a user is most likely to spend reading time

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

diff --git a/lib/DBIx/Class/Manual/Reading.pod b/lib/DBIx/Class/Manual/Reading.pod
index 02b6dcd..cb352a2 100644 (file)
--- a/lib/DBIx/Class/Manual/Reading.pod
+++ b/lib/DBIx/Class/Manual/Reading.pod
@@ -17,14 +17,14 @@ additions are consistent with the rest of the documentation.
 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
+it. Methods may also be documented and referred 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
+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.
 
@@ -46,7 +46,7 @@ of the arguments the method is expected to take, and an indication of
 what the method returns.
 
 The first item provides a list of all possible values for the
-arguments of the method in order, separated by C<, >, preceeded by the
+arguments of the method in order, separated by C<, >, preceded by the
 text "Arguments: "
 
 Example (for the belongs_to relationship):
@@ -89,6 +89,20 @@ method arguments, use with caution.
 
 =item *
 
+L<$obj|DBIx::Class> - Reference to the source class or object definition
+
+All arguments and return values should provide a link to the object's
+class documentation or definition, even if it's the same class as the current
+documentation.  For example:
+
+  ## Correct, if stated within DBIx::Class::ResultSet
+  L<$resultset|/new>
+
+  ## Correct, if stated outside DBIx::Class::ResultSet
+  L<$resultset|DBIx::Class::ResultSet>
+
+=item *
+
 ? - Optional, should be placed after the argument type and name.
 
   ## Correct
@@ -105,33 +119,35 @@ caller should pass C<undef> in place of the missing argument.
 
 =item *
 
-| - Alternate argument content types. 
+| - Alternate argument content types.
 
 At least one of these must be supplied unless the argument is also
 marked optional.
 
 =back
 
-The second item starts with the text "Return value:". The remainder of
-the line is either the text "undefined", a text describing the result of
-the method, or a variable with a descriptive name.
+The second item starts with the text "Return Value:". The remainder of
+the line is either the text "not defined" or a variable with a descriptive
+name.
 
   ## Good examples
-  =item Return value: undefined
-  =item Return value: A schema object
-  =item Return value: $classname
+  =item Return Value: not defined
+  =item Return Value: L<$schema|DBIx::Class::Schema>
+  =item Return Value: $classname
 
   ## Bad examples
-  =item Return value: The names
+  =item Return Value: The names
 
-"undefined" means the method does not deliberately return a value, and
-the caller should not use or rely on anything it does return. (Perl
+"not defined" means the method does not deliberately return a value, and
+the caller should not use or rely on anything it does return.  (Perl
 functions always return something, usually the result of the last code
-statement, if there is no explicit return statement.)
+statement, if there is no explicit return statement.)  This is different
+than specifying "undef", which means that it explicitly returns undef,
+though usually this is used an alternate return (like C<$obj | undef>).
 
 =item *
 
-The argument list is followed by a single paragraph describing what
+The argument/return list is followed by a single paragraph describing what
 the method does.
 
 =item *
@@ -144,11 +160,11 @@ self-explanatory enough to not require it. Use best judgement.
 
 =item *
 
-The argument list is followed by some examples of how to use the
-method, using it's various types of arguments.
+The argument/return list is followed by some examples of how to use the
+method, using its 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
+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.
 
@@ -163,15 +179,12 @@ Examples and explaining paragraphs can be repeated as necessary.
 
 =back
 
-=head1 AUTHORS
+=head1 AUTHOR AND CONTRIBUTORS
 
-see L<DBIx::Class>
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
 
 =head1 LICENSE
 
 You may distribute this code under the same terms as Perl itself.
 
 =cut
-
-
-