Difference between revisions of "Modules"

From EPrints Documentation
Jump to: navigation, search
(Public Methods)
(General)
Line 2: Line 2:
 
Please write your code to the general [[http://wiki.eprints.org/w/StyleGuide StyleGuide]] of EPrints
 
Please write your code to the general [[http://wiki.eprints.org/w/StyleGuide StyleGuide]] of EPrints
  
Below the license block the name, description and synopsis (a synopsis is an example of usage). Lastly the METHODS title begins the section for inline subroutine documentation.
+
Below the license block, you need to document the name, description and synopsis (a synopsis is an example of usage) of the Package.
 
<pre>
 
<pre>
 
=head1 NAME
 
=head1 NAME
Line 25: Line 25:
 
=cut
 
=cut
 
</pre>
 
</pre>
 +
 +
After this overview section, the METHODS title begins the section for inline subroutine documentation.
 +
 
==Methods==
 
==Methods==
 
===Public Methods===
 
===Public Methods===

Revision as of 09:31, 12 August 2009

General

Please write your code to the general [StyleGuide] of EPrints

Below the license block, you need to document the name, description and synopsis (a synopsis is an example of usage) of the Package.

	=head1 NAME

	EPrints::MyModule - A one line description of MyModule

	=head1 DESCRIPTION

	One or two paragraphs explaining the function of EPrints::MyModule.

	=head1 SYNOPSIS

		use EPrints::MyModule;

		my $obj = EPrints::MyModule->new( $opts );
		$obj->do_thing( $thingy );

	=head1 METHODS

	=over 4

	=cut

After this overview section, the METHODS title begins the section for inline subroutine documentation.

Methods

Public Methods

Each public subroutine should have POD documentation above it, with hashes to separate it from the method above. A large module should probably be split into different sections, e.g. "CONSTRUCTOR METHODS", "ACCESSOR METHODS", etc. Private methods can be documented using Perl comments.

	######################################################################
        =pod

	=item $objname = EPrints::StyleGuide->my_sub( $arg1, [$opt_arg2], \%opts )

	A description of what my_sub does and arguments it takes ($opt_arg2 is
	shown as optional by using brackets).

	A description of $arg1 if needed, along with an example:

		EPrints::StyleGuide->my_sub( "eprintid" );

		EPrints::StyleGuide->my_sub(
			$arg1,
			undef,
			{
				opt1 => $var1, # What is var1
				opt2 => $var2, # What is var2
			}
		);

	Further elaboration on the effect of $var2.

	=cut

	######################################################################

	sub my_sub
	{
		...
	}

Private Methods