Bug 301967: Some .pm files have invalid POD syntax - Patch by Frédéric Buclin <LpSolit@gmail.com> r=wurblzap a=justdave

12 files changed, 86 insertions, 48 deletions

diff --git a/Bugzilla/Auth.pm b/Bugzilla/Auth.pm
index 887caf049..ba32277b7 100644
--- a/Bugzilla/Auth.pm
+++ b/Bugzilla/Auth.pm
@@ -184,8 +184,6 @@ the status codes defined in L<Bugzilla::Constants|Bugzilla::Constants> and
 described below.  The rest of the return values are status code-specific 
 and are explained in the status code descriptions.
 
-=over 4
-
 =item C<AUTH_OK>
 
 Authentication succeeded. The third variable is the userid of the new
@@ -232,8 +230,6 @@ is some text explaining why the account was disabled. This text would
 typically come from the C<disabledtext> field in the C<profiles> table.
 Note that this argument is a string, not a tag.
 
-=back
-
 =item C<current_verify_class>
 
 This scalar gets populated with the full name (eg.,
@@ -269,6 +265,8 @@ by trying cookies as a fallback.
 
 The login interface consists of the following methods:
 
+=over 4
+
 =item C<login>, which takes a C<$type> argument, using constants found in
 C<Bugzilla::Constants>.
 
@@ -281,8 +279,6 @@ login method to prompt the user for this data.
 
 The constants accepted by C<login> include the following:
 
-=over 4
-
 =item C<LOGIN_OPTIONAL>
 
 A login is never required to access this data. Attempting to login is
@@ -299,14 +295,10 @@ I<requirelogin> parameter.
 
 A login is always required to access this data.
 
-=back
-
 =item C<logout>, which takes a C<Bugzilla::User> argument for the user
 being logged out, and an C<$option> argument. Possible values for
 C<$option> include:
 
-=over 4
-
 =item C<LOGOUT_CURRENT>
 
 Log out the user and invalidate his currently registered session.
diff --git a/Bugzilla/Auth/Login/WWW.pm b/Bugzilla/Auth/Login/WWW.pm
index f54e5760b..f4bb102b1 100644
--- a/Bugzilla/Auth/Login/WWW.pm
+++ b/Bugzilla/Auth/Login/WWW.pm
@@ -104,10 +104,12 @@ Bugzilla::Auth::Login::WWW - WWW login information gathering module
 
 =head1 METHODS
 
+=over
+
 =item C<login>
 
 Passes C<login> calls to each class defined in the param C<user_info_class>
 and returns a C<Bugzilla::User> object from the first one that successfully
 gathers user login information.
 
-
+=back
diff --git a/Bugzilla/DB.pm b/Bugzilla/DB.pm
index f3b9e4ed9..7d1623b7b 100644
--- a/Bugzilla/DB.pm
+++ b/Bugzilla/DB.pm
@@ -835,7 +835,9 @@ sub _bz_init_schema_storage {
  Params:      none
  Returns:     A C<Bugzilla::DB::Schema> object representing the database
               as it exists on the disk.
+
 =cut
+
 sub _bz_real_schema {
     my ($self) = @_;
     return $self->{private_real_schema} if exists $self->{private_real_schema};
@@ -852,7 +854,6 @@ sub _bz_real_schema {
     return $self->{private_real_schema};
 }
 
-
 =item C<_bz_store_real_schema()>
 
  Description: Stores the _bz_real_schema structures in the database
@@ -863,7 +864,12 @@ sub _bz_real_schema {
 
  Precondition: $self->{_bz_real_schema} must exist.
 
+=back
+
+=end private
+
 =cut
+
 sub _bz_store_real_schema {
     my ($self) = @_;
 
@@ -890,9 +896,6 @@ sub _bz_store_real_schema {
 1;
 
 __END__
-=back
-
-=end private
 
 =head1 NAME
 
@@ -912,7 +915,7 @@ Bugzilla::DB - Database access routines, using L<DBI>
 
   # Execute the query
   $sth->execute;
-  
+
   # Get the results
   my @result = $sth->fetchrow_array;
 
@@ -982,6 +985,9 @@ Bugzilla::DB module, this would be "Mysql." For PostgreSQL it would be "Pg."
 
 The minimum version of the DBD module that we require for this database.
 
+=back
+
+
 =head1 CONNECTION
 
 A new database handle to the required database can be created using this
@@ -1038,6 +1044,7 @@ should not be called from anywhere else.
 
 =back
 
+
 =head1 ABSTRACT METHODS
 
 Note: Methods which can be implemented generically for all DBs are implemented in
@@ -1218,14 +1225,15 @@ formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
               back). False (0) or no param if the operation succeeded.
  Returns:     none
 
+=back
+
+
 =head1 IMPLEMENTED METHODS
 
 These methods are implemented in Bugzilla::DB, and only need
 to be implemented in subclasses if you need to override them for 
 database-compatibility reasons.
 
-=over 4
-
 =head2 General Information Methods
 
 These methods return information about data in the database.
@@ -1244,6 +1252,8 @@ These methods return information about data in the database.
               $column = name of column containing serial data type (scalar)
  Returns:     Last inserted ID (scalar)
 
+=back
+
 
 =head2 Schema Modification Methods
 
@@ -1398,6 +1408,9 @@ MySQL only.
  Params:      none
  Returns:     List of all the "bug" fields
 
+=back
+
+
 =head2 Transaction Methods
 
 These methods deal with the starting and stopping of transactions 
@@ -1425,6 +1438,9 @@ in the database.
  Params:      none
  Returns:     none
 
+=back
+
+
 =head1 SUBCLASS HELPERS
 
 Methods in this class are intended to be used by subclasses to help them
@@ -1445,6 +1461,7 @@ with their functions.
 
 =back
 
+
 =head1 DEPRECATED ROUTINES
 
 Several database routines are deprecated. They should not be used in new code,
@@ -1482,6 +1499,7 @@ PopGlobalSQLState
 
 =back
 
+
 =head1 SEE ALSO
 
 L<DBI>
diff --git a/Bugzilla/DB/Mysql.pm b/Bugzilla/DB/Mysql.pm
index 25c3d5f3d..0951cdc5f 100644
--- a/Bugzilla/DB/Mysql.pm
+++ b/Bugzilla/DB/Mysql.pm
@@ -494,7 +494,7 @@ sub bz_setup_database {
 
 =begin private
 
-=head 1 MYSQL-SPECIFIC DATABASE-READING METHODS
+=head1 MYSQL-SPECIFIC DATABASE-READING METHODS
 
 These methods read information about the database from the disk,
 instead of from a Schema object. They are only reliable for MySQL 
@@ -611,12 +611,14 @@ sub bz_index_list_real {
 
 =back
 
-=head 1 MYSQL-SPECIFIC "SCHEMA BUILDER"
+=head1 MYSQL-SPECIFIC "SCHEMA BUILDER"
 
 MySQL needs to be able to read in a legacy database (from before 
 Schema existed) and create a Schema object out of it. That's what
 this code does.
 
+=end private
+
 =cut
 
 # This sub itself is actually written generically, but the subroutines
@@ -653,10 +655,3 @@ sub _bz_build_schema_from_disk {
     return $schema;
 }
 1;
-
-__END__
-
-=back
-
-=end private
-
diff --git a/Bugzilla/DB/Schema.pm b/Bugzilla/DB/Schema.pm
index 300a97b98..f86f47965 100644
--- a/Bugzilla/DB/Schema.pm
+++ b/Bugzilla/DB/Schema.pm
@@ -72,6 +72,7 @@ module directly, but should instead rely on methods provided by
 Bugzilla::DB.
 
 =cut
+
 #--------------------------------------------------------------------------
 # Define the Bugzilla abstract database schema and version as constants.
 
@@ -1032,13 +1033,13 @@ DB-specific code in a subclass. Methods which are prefixed with C<_>
 are considered protected. Subclasses may override these methods, but
 other modules should not invoke these methods directly.
 
-=over 4
-
 =cut
 
 #--------------------------------------------------------------------------
 sub new {
 
+=over
+
 =item C<new>
 
  Description: Public constructor method used to instantiate objects of this
@@ -1383,6 +1384,7 @@ sub get_add_column_ddl {
  Returns:     An array of SQL statements.
 
 =cut
+
     my ($self, $table, $column, $definition, $init_value) = @_;
     my @statements;
     push(@statements, "ALTER TABLE $table ADD COLUMN $column " .
@@ -1565,6 +1567,7 @@ sub get_drop_index_ddl {
  Returns:     An array of SQL statements.
 
 =cut
+
     my ($self, $table, $name) = @_;
 
     # Although ANSI SQL-92 doesn't specify a method of dropping an index,
@@ -1594,6 +1597,7 @@ sub get_drop_column_ddl {
  Returns:     An array of SQL statements.
 
 =cut
+
 sub get_drop_table_ddl {
     my ($self, $table) = @_;
     return ("DROP TABLE $table");
@@ -1626,6 +1630,7 @@ sub get_rename_column_ddl {
  Returns:     nothing
 
 =cut
+
 sub delete_table {
     my ($self, $name) = @_;
 
@@ -1674,6 +1679,7 @@ sub get_column_abstract {
               undef.
 
 =cut
+
 sub get_indexes_on_column_abstract {
     my ($self, $table, $column) = @_;
     my %ret_hash;
@@ -1702,7 +1708,7 @@ sub get_indexes_on_column_abstract {
 
 sub get_index_abstract {
 
-=item C<get_index_abstract($table, $index)
+=item C<get_index_abstract($table, $index)>
 
  Description: Returns an index definition from the internal abstract schema.
  Params:      $table - The table the index is on.
@@ -1751,6 +1757,7 @@ sub get_table_abstract {
  Returns:     nothing
 
 =cut
+
 sub add_table {
     my ($self, $name, $definition) = @_;
     (die "Table already exists: $name")
@@ -1898,6 +1905,7 @@ sub _set_object {
  Returns:     nothing
 
 =cut
+
 sub delete_index {
     my ($self, $table, $name) = @_;
 
@@ -1921,6 +1929,9 @@ sub columns_equal {
  Params:      $col_one, $col_two - The columns to compare. Hash 
                   references, in C<ABSTRACT_SCHEMA> format.
  Returns:     C<1> if the columns are identical, C<0> if they are not.
+
+=back
+
 =cut
 
     my $self = shift;
@@ -1958,6 +1969,7 @@ sub columns_equal {
               is either store it somewhere or deserialize it.
 
 =cut
+
 sub serialize_abstract {
     my ($self) = @_;
     # We do this so that any two stored Schemas will have the
@@ -1981,6 +1993,7 @@ sub serialize_abstract {
               However, it will represent the serialized data instead of
               ABSTRACT_SCHEMA.
 =cut
+
 sub deserialize_abstract {
     my ($class, $serialized, $version) = @_;
 
@@ -2005,6 +2018,8 @@ sub deserialize_abstract {
 These methods are generally called on the class instead of on a specific
 object.
 
+=over
+
 =item C<get_empty_schema()>
 
  Description: Returns a Schema that has no tables. In effect, this
@@ -2012,6 +2027,8 @@ object.
  Params:      none
  Returns:     A "empty" Schema object.
 
+=back
+
 =cut
 
 sub get_empty_schema {
@@ -2020,9 +2037,8 @@ sub get_empty_schema {
 }
 
 1;
-__END__
 
-=back
+__END__
 
 =head1 ABSTRACT DATA TYPES
 
diff --git a/Bugzilla/Error.pm b/Bugzilla/Error.pm
index ecc430cb5..0f4caf274 100644
--- a/Bugzilla/Error.pm
+++ b/Bugzilla/Error.pm
@@ -154,7 +154,7 @@ Bugzilla::Error - Error handling utilities for Bugzilla
 
   ThrowUserError("error_tag",
                  { foo => 'bar' });
- 
+
 =head1 DESCRIPTION
 
 Various places throughout the Bugzilla codebase need to report errors to the
diff --git a/Bugzilla/Field.pm b/Bugzilla/Field.pm
index 173ff5499..ed82f805b 100644
--- a/Bugzilla/Field.pm
+++ b/Bugzilla/Field.pm
@@ -57,7 +57,6 @@ sub check_form_field_defined ($$) {
 
 Bugzilla::Field - Useful routines for fields manipulation
 
-
 =head1 SYNOPSIS
 
   use Bugzilla::Field;
diff --git a/Bugzilla/Flag.pm b/Bugzilla/Flag.pm
index b0a0586c2..65636d78c 100644
--- a/Bugzilla/Flag.pm
+++ b/Bugzilla/Flag.pm
@@ -95,8 +95,6 @@ use vars qw($template $vars);
 basic sets of columns and tables for getting flag types from th
 database.  B<Used by get, match, sqlify_criteria and perlify_record>
 
-=back
-
 =cut
 
 my @base_columns = 
@@ -129,10 +127,14 @@ my @base_tables = ("flags");
 
 =head1 PUBLIC FUNCTIONS
 
-=over C<get($id)>
+=over
+
+=item C<get($id)>
 
 Retrieves and returns a flag from the database.
 
+=back
+
 =cut
 
 # !!! Implement a cache for this function!
@@ -723,7 +725,7 @@ sub clear {
 
 =over
 
-=item C<FormToNewFlags($target, $cgi)
+=item C<FormToNewFlags($target, $cgi)>
 
 Checks whether or not there are new flags to create and returns an
 array of flag objects. This array is then passed to Flag::create().
@@ -1022,6 +1024,8 @@ Converts a row from the database into a Perl record.
 
 =back
 
+=end private
+
 =cut
 
 sub perlify_record {
@@ -1044,8 +1048,6 @@ sub perlify_record {
     return $flag;
 }
 
-=end private
-
 =head1 SEE ALSO
 
 =over
@@ -1054,6 +1056,7 @@ sub perlify_record {
 
 =back
 
+
 =head1 CONTRIBUTORS
 
 =over
diff --git a/Bugzilla/FlagType.pm b/Bugzilla/FlagType.pm
index 97c6f2c0e..49c9f777e 100644
--- a/Bugzilla/FlagType.pm
+++ b/Bugzilla/FlagType.pm
@@ -117,6 +117,7 @@ my @base_tables = ("flagtypes");
 ######################################################################
 # Public Functions
 ######################################################################
+
 =head1 PUBLIC FUNCTIONS/METHODS
 
 =over
@@ -597,6 +598,8 @@ sub perlify_record {
     return $type;
 }
 
+1;
+
 =end private
 
 =head1 SEE ALSO
@@ -618,5 +621,3 @@ sub perlify_record {
 =back
 
 =cut
-
-1;
diff --git a/Bugzilla/User.pm b/Bugzilla/User.pm
index 9f88c8aac..f9efcd248 100644
--- a/Bugzilla/User.pm
+++ b/Bugzilla/User.pm
@@ -1283,6 +1283,8 @@ L<Bugzilla-E<gt>user|Bugzilla/"user">.
 
 =head1 CONSTANTS
 
+=over
+
 =item C<USER_MATCH_MULTIPLE>
 
 Returned by C<match_field()> when at least one field matched more than 
@@ -1303,6 +1305,8 @@ user.
 Passed in to match_field to tell match_field to never display a 
 confirmation screen.
 
+=back
+
 =head1 METHODS
 
 =over 4
@@ -1565,11 +1569,11 @@ for flag mail.
 
 =head1 CLASS FUNCTIONS
 
-=over4
-
 These are functions that are not called on a User object, but instead are
 called "statically," just like a normal procedural function.
 
+=over 4
+
 =item C<insert_new_user>
 
 Creates a new user in the database.
diff --git a/Bugzilla/User/Setting.pm b/Bugzilla/User/Setting.pm
index a5ce9411f..450d20a7f 100644
--- a/Bugzilla/User/Setting.pm
+++ b/Bugzilla/User/Setting.pm
@@ -279,15 +279,18 @@ sub set {
 __END__
 
 =head1 NAME
+
 Bugzilla::User::Setting - Object for a user preference setting
 
 =head1 SYNOPSIS
+
 Setting.pm creates a setting object, which is a hash containing the user
 preference information for a single preference for a single user. These 
 are usually accessed through the "settings" object of a user, and not 
 directly.
 
 =head1 DESCRIPTION
+
 use Bugzilla::User::Setting;
 my $settings;
 
@@ -343,13 +346,17 @@ Params:      C<$setting_name> - string - the name of the setting
 Returns:     nothing
 
 =begin private
+
 =item C<_setting_exists>
 
 Description: Determines if a given setting exists in the database.
 Params:      C<$setting_name> - string - the setting name
 Returns:     boolean - true if the setting already exists in the DB.
 
+=back
+
 =end private
+
 =head1 METHODS
 
 =over 4
@@ -386,4 +393,4 @@ Description: If a user chooses to use their own value rather than the
 Params:      C<$value> - string - the new value for this setting for this user.
 Returns:     nothing
 
-
+=back
diff --git a/Bugzilla/Util.pm b/Bugzilla/Util.pm
index 6422984c2..b694de752 100644
--- a/Bugzilla/Util.pm
+++ b/Bugzilla/Util.pm
@@ -400,7 +400,7 @@ Bugzilla::Util - Generic utility functions for bugzilla
 
   # Functions for decoding
   $rv = url_decode($var);
-  
+
   # Functions that tell you about your environment
   my $is_cgi = i_am_cgi();
 
@@ -591,8 +591,6 @@ The intended use of this function is to wrap comments that are about to be
 displayed or emailed. Generally, wrapped text should not be stored in the
 database.
 
-=back
-
 =item C<find_wrap_point($string, $maxpos)>
 
 Search for a comma, a whitespace or a hyphen to split $string, within the first
@@ -622,6 +620,9 @@ the routine has to "guess" the date format that was passed to $dbh->sql_date_for
 Returns a number with 2 digit precision, unless the last digit is a 0. Then it 
 returns only 1 digit precision.
 
+=back
+
+
 =head2 Files
 
 =over 4