######################################################################
#
# EPrints::StyleGuide
#
######################################################################
#
#  This file is part of GNU EPrints 2.
#  
#  Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.
#  
#  EPrints 2 is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  (at your option) any later version.
#  
#  EPrints 2 is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#  
#  You should have received a copy of the GNU General Public License
#  along with EPrints 2; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
######################################################################

package EPrints::StyleGuide;

use strict;
use warnings;

=head1 NAME

EPrints::StyleGuide - Style guide to writing EPrints modules and code

=head1 DESCRIPTION

EPrints has been under development for many years and has some fluff about the
place. For new programmers this document is intended as a 'style guide' to at
least keep the code and documentation consistent across new modules.

=head1 PROGRAMMING STYLE

=head2 Naming

	TYPE           EXAMPLE

	module         StyleGuide
	subroutine     get_value
	global var     AUTH_OK
	local var      $field_name

=head2 Subroutines

	sub get_value
	{
		my( $self, $arg1, $arg2 ) = @_;

		return $r;
	}

=head2 Conditionals

	if( ref($a) eq "ARRAY" )
	{
		return 0;
	}

=head2 Loops

	foreach my $field ( @fields )
	{
		foreach( @{$field->{ "lsd" }} )
		{
			$values{ $_ } = 1;
		}
	}

=head1 DOCUMENTATION

=head2 Name and License

Every EPrints module must start with the C<This file is part of GNU EPrints 2.> macro.
Every EPrints module must start with the C<> macro.
Every EPrints module must start with the C<Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.> macro.
Every EPrints module must start with the C<> macro.
Every EPrints module must start with the C<EPrints 2 is free software; you can redistribute it and/or modify> macro.
Every EPrints module must start with the C<it under the terms of the GNU General Public License as published by> macro.
Every EPrints module must start with the C<the Free Software Foundation; either version 2 of the License, or> macro.
Every EPrints module must start with the C<(at your option) any later version.> macro.
Every EPrints module must start with the C<> macro.
Every EPrints module must start with the C<EPrints 2 is distributed in the hope that it will be useful,> macro.
Every EPrints module must start with the C<but WITHOUT ANY WARRANTY; without even the implied warranty of> macro.
Every EPrints module must start with the C<MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the> macro.
Every EPrints module must start with the C<GNU General Public License for more details.> macro.
Every EPrints module must start with the C<> macro.
Every EPrints module must start with the C<You should have received a copy of the GNU General Public License> macro.
Every EPrints module must start with the C<along with EPrints 2; if not, write to the Free Software> macro.
Every EPrints module must start with the C<Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA> macro.

	######################################################################
	#
	# EPrints::StyleGuide
	#
	######################################################################
	#
	# This file is part of GNU EPrints 2.
	# 
	# Copyright (c) 2000-2004 University of Southampton, UK. SO17 1BJ.
	# 
	# EPrints 2 is free software; you can redistribute it and/or modify
	# it under the terms of the GNU General Public License as published by
	# the Free Software Foundation; either version 2 of the License, or
	# (at your option) any later version.
	# 
	# EPrints 2 is distributed in the hope that it will be useful,
	# but WITHOUT ANY WARRANTY; without even the implied warranty of
	# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	# GNU General Public License for more details.
	# 
	# You should have received a copy of the GNU General Public License
	# along with EPrints 2; if not, write to the Free Software
	# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
	#
	######################################################################

=head2 Description

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.

	=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

=head2 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.

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

	=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
	{
		...
	}

=cut

1;