Difference between revisions of "Modules"

From EPrints Documentation
Jump to: navigation, search
m (Change category Developer to Contribute)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Category:Contribute]]
 
==General==
 
==General==
 
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 26:
 
=cut
 
=cut
 
</pre>
 
</pre>
 +
 +
After this overview section, the METHODS title begins the section for inline subroutine documentation.
 +
 
==Methods==
 
==Methods==
 
===Public Methods===
 
===Public Methods===
Line 33: Line 37:
 
<pre>
 
<pre>
 
######################################################################
 
######################################################################
 +
        =pod
  
 
=item $objname = EPrints::StyleGuide->my_sub( $arg1, [$opt_arg2], \%opts )
 
=item $objname = EPrints::StyleGuide->my_sub( $arg1, [$opt_arg2], \%opts )
Line 63: Line 68:
 
}
 
}
 
</pre>
 
</pre>
 +
 
===Private Methods===
 
===Private Methods===
 +
Private methods do not have public documentation, but they '''do''' need documented, so provide the information within a standard perl comment:
 +
 +
<pre>
 +
######################################################################
 +
#
 +
# $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
 +
 +
}
 +
</pre>

Latest revision as of 23:52, 11 September 2018

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

}