DBIx::Class::Manual::Reading man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

DBIx::Class::Manual::RUsernContributed Perl DocDBIx::Class::Manual::Reading(3)

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

DESCRIPTION
       This doc should help users to understand how the examples and
       documentation found in the 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.

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 referred to in files representing
       the major objects or components on which they can be called.

       For example, 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 DBIx::Class::Row, the major object
       that they will be called on.

   Method documentation
       ·   Each method starts with a "head2" statement of its name.

	   Just the plain method name, not an example of how to call it, or a
	   link.  This is to ensure easy linking to method documentation from
	   other POD.

       ·   The header is followed by a two-item list. This contains a
	   description 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 ", ", preceded 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:

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

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

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

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

	   ·   %var - A hashref variable (list of key/value pairs) - rarely
	       used in DBIx::Class.

	       Reading an argument as a hash variable will consume all
	       subsequent method arguments, use with caution.

	   ·   @var - An array variable (list of values).

	       Reading an argument as a array variable will consume all
	       subsequent method arguments, use with caution.

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

		 ## Correct
		 \%myhashref|\@myarrayref?

		 ## Wrong
		 \%myhashref?|\@myarrayref

	       Applies to the entire argument.

	       Optional arguments can be left out of method calls, unless the
	       caller needs to pass in any of the following arguments. In
	       which case the caller should pass "undef" in place of the
	       missing argument.

	   ·   | - Alternate argument content types.

	       At least one of these must be supplied unless the argument is
	       also marked optional.

	   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.

	     ## Good examples
	     =item Return value: undefined
	     =item Return value: A schema object
	     =item Return value: $classname

	     ## Bad examples
	     =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 functions always return something, usually the result of the
	   last code statement, if there is no explicit return statement.)

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

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

	   This list may be omitted if the author feels that the variable
	   names are self-explanatory enough to not require it. Use best
	   judgement.

       ·   The argument 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 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.

AUTHORS
       see DBIx::Class

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

perl v5.14.2			  2012-01-22   DBIx::Class::Manual::Reading(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net