Modules

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

Private methods do not have public documentation, but they do need documented, so provide the information within a standard perl comment:

######################################################################
#
# $id = $session->_find_foo
#
# This is where we do some clever stuff, and find the foo in the bar
# (or, failing that, have a wee drink in the bar, before going back to
# work!
#
######################################################################
sub _find_foo
{
    my( $self ) = @_;

    my $sesh = $self->{session};

    # mix it up, slosh it around... define $whatever

    return $whatever

}