Bug 350649: Improve the rendering of POD from Bugzilla::DB

Patch By Max Kanat-Alexander <mkanat@bugzilla.org> (module owner) a=myk

1 files changed, 874 insertions, 334 deletions

diff --git a/Bugzilla/DB.pm b/Bugzilla/DB.pm
index 71669b714..9378054b3 100644
--- a/Bugzilla/DB.pm
+++ b/Bugzilla/DB.pm
@@ -1089,82 +1089,141 @@ should not be called from anywhere else.
 
 =head2 Functions
 
-=over 4
+=over
 
 =item C<connect_main>
 
- Description: Function to connect to the main database, returning a new
-              database handle.
- Params:      $no_db_name (optional) - If true, Connect to the database 
-                  server, but don't connect to a specific database. This 
-                  is only used when creating a database. After you create
-                  the database, you should re-create a new Bugzilla::DB object
-                  without using this parameter. 
- Returns:     new instance of the DB class
+=over
+
+=item B<Description>
+
+Function to connect to the main database, returning a new database handle.
+
+=item B<Params>
+
+=over
+
+=item C<$no_db_name> (optional) - If true, connect to the database
+server, but don't connect to a specific database. This is only used 
+when creating a database. After you create the database, you should 
+re-create a new Bugzilla::DB object without using this parameter. 
+
+=back
+
+=item B<Returns>
+
+New instance of the DB class
+
+=back
 
 =item C<connect_shadow>
 
- Description: Function to connect to the shadow database, returning a new
-              database handle.
-              This routine C<die>s if no shadow database is configured.
- Params:      none
- Returns:     new instance of the DB class
+=over
+
+=item B<Description>
+
+Function to connect to the shadow database, returning a new database handle.
+This routine C<die>s if no shadow database is configured.
+
+=item B<Params> (none)
+
+=item B<Returns>
+
+A new instance of the DB class
+
+=back
+
+=item C<bz_check_requirements>
+
+=over
+
+=item B<Description>
+
+Checks to make sure that you have the correct DBD and database version 
+installed for the database that Bugzilla will be using. Prints a message 
+and exits if you don't pass the requirements.
+
+If C<$db_check> is false (from F<localconfig>), we won't check the 
+database version.
+
+=item B<Params>
+
+=over
+
+=item C<$output> - C<true> if the function should display informational 
+output about what it's doing, such as versions found.
 
-=item C<bz_check_requirements($output)>
+=back
+
+=item B<Returns> (nothing)
+
+=back
 
-Description: Checks to make sure that you have the correct
-             DBD and database version installed for the
-             database that Bugzilla will be using.
-             Prints a message and exits if you don't
-             pass the requirements.
-             If C<$db_check> is true (from F<localconfig>), we won't
-             check the database version.
 
-Params:      C<$output> - C<true> if the function should display
-                 informational output about what it's doing, such
-                 as versions found.
+=item C<bz_create_database>
 
-Returns:     nothing
+=over
 
-=item C<bz_create_database()>
+=item B<Description>
 
-Description: Creates an empty database with the name
-             C<$db_name>, if that database doesn't
-             already exist. Prints an error message and
-             exits if we can't create the database.
+Creates an empty database with the name C<$db_name>, if that database 
+doesn't already exist. Prints an error message and exits if we can't 
+create the database.
 
-Params:      none
+=item B<Params> (none)
 
-Returns:     nothing
+=item B<Returns> (nothing)
+
+=back
 
 =item C<_connect>
 
- Description: Internal function, creates and returns a new, connected
-              instance of the correct DB class.
-              This routine C<die>s if no driver is specified.
- Params:      $driver = name of the database driver to use
-              $host = host running the database we are connecting to
-              $dbname = name of the database to connect to
-              $port = port the database is listening on
-              $sock = socket the database is listening on
-              $user = username used to log in to the database
-              $pass = password used to log in to the database
- Returns:     new instance of the DB class
+=over
+
+=item B<Description>
+
+Internal function, creates and returns a new, connected instance of the 
+correct DB class.  This routine C<die>s if no driver is specified.
+
+=item B<Params>
+
+=over
+
+=item C<$driver> - name of the database driver to use
+
+=item C<$host> - host running the database we are connecting to
+
+=item C<$dbname> - name of the database to connect to
+
+=item C<$port> - port the database is listening on
+
+=item C<$sock> - socket the database is listening on
+
+=item C<$user> - username used to log in to the database
+
+=item C<$pass> - password used to log in to the database
+
+=back
+
+=item B<Returns>
+
+A new instance of the DB class
+
+=back
 
 =item C<_handle_error>
 
- Description: Function passed to the DBI::connect call for error handling.
-              It shortens the error for printing.
+Function passed to the DBI::connect call for error handling. It shortens the 
+error for printing.
 
 =item C<import>
 
- Description: Overrides the standard import method to check that derived class
-              implements all required abstract methods. Also calls original
-              implementation in its super class.
+Overrides the standard import method to check that derived class
+implements all required abstract methods. Also calls original implementation 
+in its super class.
 
 =back
 
-
 =head1 ABSTRACT METHODS
 
 Note: Methods which can be implemented generically for all DBs are implemented in
@@ -1174,185 +1233,478 @@ be implemented for all supported databases separately.
 To avoid confusion with standard DBI methods, all methods returning string with
 formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
 
-=over 4
+=head2 Constructor
+
+=over
 
 =item C<new>
 
- Description: Constructor
-              Abstract method, should be overridden by database specific code.
- Params:      $user = username used to log in to the database
-              $pass = password used to log in to the database
-              $host = host running the database we are connecting to
-              $dbname = name of the database to connect to
-              $port = port the database is listening on
-              $sock = socket the database is listening on
- Returns:     new instance of the DB class
- Note:        The constructor should create a DSN from the parameters provided and
-              then call C<db_new()> method of its super class to create a new
-              class instance. See C<db_new> description in this module. As per
-              DBI documentation, all class variables must be prefixed with
-              "private_". See L<DBI>.
+=over
+
+=item B<Description>
+
+Constructor.  Abstract method, should be overridden by database specific 
+code.
+
+=item B<Params>
+
+=over 
+
+=item C<$user> - username used to log in to the database
+
+=item C<$pass> - password used to log in to the database
+
+=item C<$host> - host running the database we are connecting to
+
+=item C<$dbname> - name of the database to connect to
+
+=item C<$port> - port the database is listening on
+
+=item C<$sock> - socket the database is listening on
+
+=back
+
+=item B<Returns>
+
+A new instance of the DB class
+
+=item B<Note>
+
+The constructor should create a DSN from the parameters provided and
+then call C<db_new()> method of its super class to create a new
+class instance. See L<db_new> description in this module. As per
+DBI documentation, all class variables must be prefixed with
+"private_". See L<DBI>.
+
+=back
+
+=back
+
+=head2 SQL Generation
+
+=over
 
 =item C<sql_regexp>
 
- Description: Outputs SQL regular expression operator for POSIX regex
-              searches (case insensitive) in format suitable for a given
-              database.
-              Abstract method, should be overridden by database specific code.
- Params:      $expr = SQL expression for the text to be searched (scalar)
-              $pattern = the regular expression to search for (scalar)
- Returns:     formatted SQL for regular expression search (e.g. REGEXP)
-              (scalar)
+=over
+
+=item B<Description>
+
+Outputs SQL regular expression operator for POSIX regex
+searches (case insensitive) in format suitable for a given
+database.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$expr> - SQL expression for the text to be searched (scalar)
+
+=item C<$pattern> - the regular expression to search for (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for regular expression search (e.g. REGEXP) (scalar)
+
+=back
 
 =item C<sql_not_regexp>
 
- Description: Outputs SQL regular expression operator for negative POSIX
-              regex searches (case insensitive) in format suitable for a given
-              database.
-              Abstract method, should be overridden by database specific code.
- Params:      $expr = SQL expression for the text to be searched (scalar)
-              $pattern = the regular expression to search for (scalar)
- Returns:     formatted SQL for negative regular expression search
-              (e.g. NOT REGEXP) (scalar)
+=over
+
+=item B<Description>
+
+Outputs SQL regular expression operator for negative POSIX
+regex searches (case insensitive) in format suitable for a given
+database.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$expr> - SQL expression for the text to be searched (scalar)
+
+=item C<$pattern> - the regular expression to search for (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for negative regular expression search (e.g. NOT REGEXP) 
+(scalar)
+
+=back
 
 =item C<sql_limit>
 
- Description: Returns SQL syntax for limiting results to some number of rows
-              with optional offset if not starting from the begining.
-              Abstract method, should be overridden by database specific code.
- Params:      $limit = number of rows to return from query (scalar)
-              $offset = number of rows to skip prior counting (scalar)
- Returns:     formatted SQL for limiting number of rows returned from query
-              with optional offset (e.g. LIMIT 1, 1) (scalar)
+=over
+
+=item B<Description>
+
+Returns SQL syntax for limiting results to some number of rows
+with optional offset if not starting from the begining.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$limit> - number of rows to return from query (scalar)
+
+=item C<$offset> - number of rows to skip prior counting (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for limiting number of rows returned from query
+with optional offset (e.g. LIMIT 1, 1) (scalar)
+
+=back
 
 =item C<sql_from_days>
 
- Description: Outputs SQL syntax for converting Julian days to date.
-              Abstract method, should be overridden by database specific code.
- Params:      $days = days to convert to date
- Returns:     formatted SQL for returning Julian days in dates. (scalar)
+=over
+
+=item B<Description>
+
+Outputs SQL syntax for converting Julian days to date.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$days> - days to convert to date
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for returning Julian days in dates. (scalar)
+
+=back
 
 =item C<sql_to_days>
 
- Description: Outputs SQL syntax for converting date to Julian days.
-              Abstract method, should be overridden by database specific code.
- Params:      $date = date to convert to days
- Returns:     formatted SQL for returning date fields in Julian days. (scalar)
+=over
+
+=item B<Description>
+
+Outputs SQL syntax for converting date to Julian days.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$date> - date to convert to days
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for returning date fields in Julian days. (scalar)
+
+=back
 
 =item C<sql_date_format>
 
- Description: Outputs SQL syntax for formatting dates.
-              Abstract method, should be overridden by database specific code.
- Params:      $date = date or name of date type column (scalar)
-              $format = format string for date output (scalar)
-              (%Y = year, four digits, %y = year, two digits, %m = month,
-               %d = day, %a = weekday name, 3 letters, %H = hour 00-23,
-               %i = minute, %s = second)
- Returns:     formatted SQL for date formatting (scalar)
+=over
+
+=item B<Description>
+
+Outputs SQL syntax for formatting dates.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$date> - date or name of date type column (scalar)
+
+=item C<$format> - format string for date output (scalar)
+(C<%Y> = year, four digits, C<%y> = year, two digits, C<%m> = month,
+C<%d> = day, C<%a> = weekday name, 3 letters, C<%H> = hour 00-23,
+C<%i> = minute, C<%s> = second)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for date formatting (scalar)
+
+=back
 
 =item C<sql_interval>
 
- Description: Outputs proper SQL syntax for a time interval function.
-              Abstract method, should be overridden by database specific code.
- Params:      $interval - the time interval requested (e.g. '30') (integer)
-              $units    - the units the interval is in (e.g. 'MINUTE') (string)
- Returns:     formatted SQL for interval function (scalar)
+=over
+
+=item B<Description>
+
+Outputs proper SQL syntax for a time interval function.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$interval> - the time interval requested (e.g. '30') (integer)
+
+=item C<$units> - the units the interval is in (e.g. 'MINUTE') (string)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for interval function (scalar)
+
+=back
 
 =item C<sql_position>
 
- Description: Outputs proper SQL syntax determinig position of a substring
-              (fragment) withing a string (text). Note: if the substring or
-              text are string constants, they must be properly quoted
-              (e.g. "'pattern'").
- Params:      $fragment = the string fragment we are searching for (scalar)
-              $text = the text to search (scalar)
- Returns:     formatted SQL for substring search (scalar)
+=over
+
+=item B<Description>
+
+Outputs proper SQL syntax determinig position of a substring
+(fragment) withing a string (text). Note: if the substring or
+text are string constants, they must be properly quoted (e.g. "'pattern'").
+
+=item B<Params>
+
+=over
+
+=item C<$fragment> - the string fragment we are searching for (scalar)
+
+=item C<$text> - the text to search (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for substring search (scalar)
+
+=back
 
 =item C<sql_group_by>
 
- Description: Outputs proper SQL syntax for grouping the result of a query.
-              For ANSI SQL databases, we need to group by all columns we are
-              querying for (except for columns used in aggregate functions).
-              Some databases require (or even allow) to specify only one
-              or few columns if the result is uniquely defined. For those
-              databases, the default implementation needs to be overloaded.
- Params:      $needed_columns = string with comma separated list of columns
-              we need to group by to get expected result (scalar)
-              $optional_columns = string with comma separated list of all
-              other columns we are querying for, but which are not in the
-              required list.
- Returns:     formatted SQL for row grouping (scalar)
+=over
+
+=item B<Description>
+
+Outputs proper SQL syntax for grouping the result of a query.
+
+For ANSI SQL databases, we need to group by all columns we are
+querying for (except for columns used in aggregate functions).
+Some databases require (or even allow) to specify only one
+or few columns if the result is uniquely defined. For those
+databases, the default implementation needs to be overloaded.
+
+=item B<Params>
+
+=over
+
+=item C<$needed_columns> - string with comma separated list of columns
+we need to group by to get expected result (scalar)
+
+=item C<$optional_columns> - string with comma separated list of all
+other columns we are querying for, but which are not in the required list.
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for row grouping (scalar)
+
+=back
 
 =item C<sql_string_concat>
 
- Description: Returns SQL syntax for concatenating multiple strings (constants
-              or values from table columns) together.
- Params:      @params = array of column names or strings to concatenate
- Returns:     formatted SQL for concatenating specified strings
+=over
+
+=item B<Description>
+
+Returns SQL syntax for concatenating multiple strings (constants
+or values from table columns) together.
+
+=item B<Params>
+
+=over
+
+=item C<@params> - array of column names or strings to concatenate
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for concatenating specified strings
+
+=back
 
 =item C<sql_fulltext_search>
 
- Description: Returns SQL syntax for performing a full text search for
-              specified text on a given column.
-              There is a ANSI SQL version of this method implemented using
-              LIKE operator, but it's not a real full text search. DB specific
-              modules should override this, as this generic implementation will
-              be always much slower. This generic implementation returns
-              'relevance' as 0 for no match, or 1 for a match.
- Params:      $column = name of column to search (scalar)
-              $text = text to search for (scalar)
- Returns:     formatted SQL for full text search
+=over
+
+=item B<Description>
+
+Returns SQL syntax for performing a full text search for specified text 
+on a given column.
+
+There is a ANSI SQL version of this method implemented using LIKE operator,
+but it's not a real full text search. DB specific modules should override 
+this, as this generic implementation will be always much slower. This 
+generic implementation returns 'relevance' as 0 for no match, or 1 for a 
+match.
+
+=item B<Params>
+
+=over
+
+=item C<$column> - name of column to search (scalar)
+
+=item C<$text> - text to search for (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL for full text search
+
+=back
 
 =item C<sql_istrcmp>
 
- Description: Returns SQL for a case-insensitive string comparison.
- Params:      $left - What should be on the left-hand-side of the
-                      operation.
-              $right - What should be on the right-hand-side of the
-                       operation.
-              $op (optional) - What the operation is. Should be a 
-                  valid ANSI SQL comparison operator, like "=", "<", 
-                  "LIKE", etc. Defaults to "=" if not specified.
- Returns:     A SQL statement that will run the comparison in 
-              a case-insensitive fashion.
- Note:        Uses sql_istring, so it has the same performance concerns.
-              Try to avoid using this function unless absolutely necessary.
-              Subclass Implementors: Override sql_istring instead of this
-              function, most of the time (this function uses sql_istring).
+=over
+
+=item B<Description>
+
+Returns SQL for a case-insensitive string comparison.
+
+=item B<Params>
+
+=over
+
+=item C<$left> - What should be on the left-hand-side of the operation.
+
+=item C<$right> - What should be on the right-hand-side of the operation.
+
+=item C<$op> (optional) - What the operation is. Should be a  valid ANSI 
+SQL comparison operator, such as C<=>, C<E<lt>>, C<LIKE>, etc. Defaults 
+to C<=> if not specified.
+
+=back
+
+=item B<Returns>
+
+A SQL statement that will run the comparison in a case-insensitive fashion.
+
+=item B<Note>
+
+Uses L</sql_istring>, so it has the same performance concerns.
+Try to avoid using this function unless absolutely necessary.
+
+Subclass Implementors: Override sql_istring instead of this
+function, most of the time (this function uses sql_istring).
+
+=back
 
 =item C<sql_istring>
 
- Description: Returns SQL syntax "preparing" a string or text column for
-              case-insensitive comparison. 
- Params:      $string - string to convert (scalar)
- Returns:     formatted SQL making the string case insensitive
- Note:        The default implementation simply calls LOWER on the parameter.
-              If this is used to search on a text column with index, the index
-              will not be usually used unless it was created as LOWER(column).
+=over
+
+=item B<Description>
+
+Returns SQL syntax "preparing" a string or text column for case-insensitive 
+comparison.
+
+=item B<Params>
+
+=over
+
+=item C<$string> - string to convert (scalar)
+
+=back
+
+=item B<Returns>
+
+Formatted SQL making the string case insensitive.
+
+=item B<Note>
+
+The default implementation simply calls LOWER on the parameter.
+If this is used to search on a text column with index, the index
+will not be usually used unless it was created as LOWER(column).
+
+=back
 
 =item C<bz_lock_tables>
 
- Description: Performs a table lock operation on specified tables.
-              If the underlying database supports transactions, it should also
-              implicitly start a new transaction.
-              Abstract method, should be overridden by database specific code.
- Params:      @tables = list of names of tables to lock in MySQL
-              notation (ex. 'bugs AS bugs2 READ', 'logincookies WRITE')
- Returns:     none
+=over
+
+=item B<Description>
+
+Performs a table lock operation on specified tables. If the underlying 
+database supports transactions, it should also implicitly start a new 
+transaction.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<@tables> - list of names of tables to lock in MySQL
+notation (ex. 'bugs AS bugs2 READ', 'logincookies WRITE')
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
 
 =item C<bz_unlock_tables>
 
- Description: Performs a table unlock operation
-              If the underlying database supports transactions, it should also
-              implicitly commit or rollback the transaction.
-              Also, this function should allow to be called with the abort flag
-              set even without locking tables first without raising an error
-              to simplify error handling.
-              Abstract method, should be overridden by database specific code.
- Params:      $abort = UNLOCK_ABORT (true, 1) if the operation on locked tables
-              failed (if transactions are supported, the action will be rolled
-              back). False (0) or no param if the operation succeeded.
- Returns:     none
+=over
+
+=item B<Description>
+
+Performs a table unlock operation.
+
+If the underlying database supports transactions, it should also implicitly 
+commit or rollback the transaction.
+
+Also, this function should allow to be called with the abort flag
+set even without locking tables first without raising an error
+to simplify error handling.
+
+Abstract method, should be overridden by database specific code.
+
+=item B<Params>
+
+=over
+
+=item C<$abort> - C<UNLOCK_ABORT> if the operation on locked tables
+failed (if transactions are supported, the action will be rolled
+back). No param if the operation succeeded. This is only used by
+L<Bugzilla::Error/throw_error>.
+
+=back
+
+=item B<Returns> (none)
+
+=back
 
 =back
 
@@ -1367,41 +1719,80 @@ database-compatibility reasons.
 
 These methods return information about data in the database.
 
-=over 4
+=over
 
 =item C<bz_last_key>
 
- Description: Returns the last serial number, usually from a previous INSERT.
-              Must be executed directly following the relevant INSERT.
-              This base implementation uses DBI->last_insert_id. If the
-              DBD supports it, it is the preffered way to obtain the last
-              serial index. If it is not supported, the DB specific code
-              needs to override it with DB specific code.
- Params:      $table = name of table containing serial column (scalar)
-              $column = name of column containing serial data type (scalar)
- Returns:     Last inserted ID (scalar)
+=over
+
+=item B<Description>
+
+Returns the last serial number, usually from a previous INSERT.
+
+Must be executed directly following the relevant INSERT.
+This base implementation uses L<DBI/last_insert_id>. If the
+DBD supports it, it is the preffered way to obtain the last
+serial index. If it is not supported, the DB-specific code
+needs to override this function.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - name of table containing serial column (scalar)
+
+=item C<$column> - name of column containing serial data type (scalar)
+
+=back
+
+=item B<Returns>
+
+Last inserted ID (scalar)
+
+=back
+
+=item C<bz_get_field_defs>
+
+=over
+
+=item B<Description>
+
+Returns a list of all the "bug" fields in Bugzilla. The list
+contains hashes, with a C<name> key and a C<description> key.
+
+=item B<Params> (none)
+
+=item B<Returns>
+
+List of all the "bug" fields
 
 =back
 
+=back
 
 =head2 Database Setup Methods
 
 These methods are used by the Bugzilla installation programs to set up
 the database.
 
-=over 4
+=over
+
+=item C<bz_populate_enum_tables>
+
+=over
+
+=item B<Description>
 
-=item C<bz_populate_enum_tables()>
+For an upgrade or an initial installation, populates the tables that hold 
+the legal values for the old "enum" fields: C<bug_severity>, 
+C<resolution>, etc. Prints out information if it inserts anything into the
+DB.
 
-Description: For an upgrade or an initial installation, populates
-             the tables that hold the legal values for the old
-             "enum" fields: C<bug_severity>, C<resolution>, etc.
-             Prints out information if it inserts anything into the
-             DB.
+=item B<Params> (none)
 
-Params:      none
+=item B<Returns> (nothing)
 
-Returns:     nothing
+=back
 
 =back
 
@@ -1414,103 +1805,220 @@ Where a parameter says "Abstract index/column definition", it returns/takes
 information in the formats defined for indexes and columns in
 C<Bugzilla::DB::Schema::ABSTRACT_SCHEMA>.
 
-=over 4
+=over
 
-=item C<bz_add_column($table, $name, \%definition, $init_value)>
-
- Description: Adds a new column to a table in the database. Prints out
-              a brief statement that it did so, to stdout.
-              Note that you cannot add a NOT NULL column that has no
-              default -- the database won't know what to set all
-              the NOT NULL values to.
- Params:      $table = the table where the column is being added
-              $name  = the name of the new column
-              \%definition = Abstract column definition for the new column
-              $init_value = (optional) An initial value to set the column
-                            to. Required if your column is NOT NULL and has
-                            no DEFAULT set.
- Returns:     nothing
+=item C<bz_add_column>
 
-=item C<bz_add_index($table, $name, $definition)>
+=over
 
- Description: Adds a new index to a table in the database. Prints
-              out a brief statement that it did so, to stdout.
-              If the index already exists, we will do nothing.
- Params:      $table - The table the new index is on.
-              $name  - A name for the new index.
-              $definition - An abstract index definition. 
-                            Either a hashref or an arrayref.
- Returns:     nothing
+=item B<Description>
 
-=item C<bz_add_table($name)>
+Adds a new column to a table in the database. Prints out a brief statement 
+that it did so, to stdout. Note that you cannot add a NOT NULL column that 
+has no default -- the database won't know what to set all the NULL
+values to.
 
- Description: Creates a new table in the database, based on the
-              definition for that table in the abstract schema.
-              Note that unlike the other 'add' functions, this does
-              not take a definition, but always creates the table
-              as it exists in the ABSTRACT_SCHEMA.
-              If a table with that name already exists, then this
-              function returns silently.
- Params:      $name - The name of the table you want to create.
- Returns:     nothing
+=item B<Params>
 
-=item C<bz_drop_index($table, $name)>
+=over
 
- Description: Removes an index from the database. Prints out a brief
-              statement that it did so, to stdout. If the index
-              doesn't exist, we do nothing.
- Params:      $table - The table that the index is on.
-              $name  - The name of the index that you want to drop.
- Returns:     nothing
+=item C<$table> - the table where the column is being added
 
-=item C<bz_drop_table($name)>
+=item C<$name> - the name of the new column
 
- Description: Drops a table from the database. If the table
-              doesn't exist, we just return silently.
- Params:      $name - The name of the table to drop.
- Returns:     nothing
+=item C<\%definition> - Abstract column definition for the new column
 
-=item C<bz_alter_column($table, $name, \%new_def, $set_nulls_to)>
-
- Description: Changes the data type of a column in a table. Prints out
-              the changes being made to stdout. If the new type is the
-              same as the old type, the function returns without changing
-              anything.
- Params:      $table   = the table where the column is
-              $name    = the name of the column you want to change
-              $new_def = An abstract column definition for the new 
-                         data type of the columm
-              $set_nulls_to = (Optional) If you are changing the column
-                              to be NOT NULL, you probably also want to
-                              set any existing NULL columns to a particular
-                              value. Specify that value here. 
-                              NOTE: The value should not already be SQL-quoted.
- Returns:     nothing
+=item C<$init_value> (optional) - An initial value to set the column
+to. Required if your column is NOT NULL and has no DEFAULT set.
 
-=item C<bz_drop_column($table, $column)>
-
- Description: Removes a column from a database table. If the column
-              doesn't exist, we return without doing anything. If we do
-              anything, we print a short message to stdout about the change.
- Params:      $table  = The table where the column is
-              $column = The name of the column you want to drop
- Returns:     none
-
-=item C<bz_rename_column($table, $old_name, $new_name)>
-
- Description: Renames a column in a database table. If the C<$old_name>
-              column doesn't exist, we return without doing anything.
-              If C<$old_name> and C<$new_name> both already exist in the
-              table specified, we fail.
- Params:      $table    = The table containing the column 
-                          that you want to rename
-              $old_name = The current name of the column that 
-                          you want to rename
-              $new_name = The new name of the column
- Returns:     nothing
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_add_index>
+
+=over
+
+=item B<Description>
+
+Adds a new index to a table in the database. Prints out a brief statement 
+that it did so, to stdout. If the index already exists, we will do nothing.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The table the new index is on.
+
+=item C<$name>  - A name for the new index.
+
+=item C<$definition> - An abstract index definition. Either a hashref 
+or an arrayref.
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_add_table>
+
+=over
+
+=item B<Description>
+
+Creates a new table in the database, based on the definition for that 
+table in the abstract schema.
+
+Note that unlike the other 'add' functions, this does not take a 
+definition, but always creates the table as it exists in
+L<Bugzilla::DB::Schema/ABSTRACT_SCHEMA>.
+
+If a table with that name already exists, then this function returns 
+silently.
+
+=item B<Params>
+
+=over
+
+=item C<$name> - The name of the table you want to create.
+
+=back
+
+=item B<Returns> (nothing)
 
 =back
 
+=item C<bz_drop_index>
+
+=over
+
+=item B<Description>
+
+Removes an index from the database. Prints out a brief statement that it 
+did so, to stdout. If the index doesn't exist, we do nothing.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The table that the index is on.
+
+=item C<$name> - The name of the index that you want to drop.
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_drop_table>
+
+=over
+
+=item B<Description>
+
+Drops a table from the database. If the table doesn't exist, we just 
+return silently.
+
+=item B<Params>
+
+=over
+
+=item C<$name> - The name of the table to drop.
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_alter_column>
+
+=over
+
+=item B<Description>
+
+Changes the data type of a column in a table. Prints out the changes 
+being made to stdout. If the new type is the same as the old type, 
+the function returns without changing anything.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - the table where the column is
+
+=item C<$name> - the name of the column you want to change
+
+=item C<\%new_def> - An abstract column definition for the new 
+data type of the columm
+
+=item C<$set_nulls_to> (Optional) - If you are changing the column
+to be NOT NULL, you probably also want to set any existing NULL columns 
+to a particular value. Specify that value here. B<NOTE>: The value should 
+not already be SQL-quoted.
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_drop_column>
+
+=over
+
+=item B<Description>
+
+Removes a column from a database table. If the column doesn't exist, we 
+return without doing anything. If we do anything, we print a short 
+message to C<stdout> about the change.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The table where the column is
+
+=item C<$column> - The name of the column you want to drop
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=item C<bz_rename_column>
+
+=over
+
+=item B<Description>
+
+Renames a column in a database table. If the C<$old_name> column 
+doesn't exist, we return without doing anything. If C<$old_name> 
+and C<$new_name> both already exist in the table specified, we fail.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The name of the table containing the column 
+that you want to rename
+
+=item C<$old_name> - The current name of the column that you want to rename
+
+=item C<$new_name> - The new name of the column
+
+=back
+
+=item B<Returns> (nothing)
+
+=back
+
+=back
 
 =head2 Schema Information Methods
 
@@ -1518,46 +2026,63 @@ These methods return information about the current Bugzilla database
 schema, as it currently exists on the disk. 
 
 Where a parameter says "Abstract index/column definition", it returns/takes
-information in the formats defined for indexes and columns in
-C<Bugzilla::DB::Schema::ABSTRACT_SCHEMA>.
+information in the formats defined for indexes and columns for
+L<Bugzilla::DB::Schema/ABSTRACT_SCHEMA>.
 
-=over 4
+=over
+
+=item C<bz_column_info>
+
+=over
 
-=item C<bz_column_info($table, $column)>
+=item B<Description>
 
- Description: Get abstract column definition.
- Params:      $table - The name of the table the column is in.
-              $column - The name of the column.
- Returns:     An abstract column definition for that column.
-              If the table or column does not exist, we return undef.
+Get abstract column definition.
 
-=item C<bz_index_info($table, $index)>
+=item B<Params>
 
- Description: Get abstract index definition.
- Params:      $table - The table the index is on.
-              $index - The name of the index.
- Returns:     An abstract index definition for that index,
-              always in hashref format. The hashref will
-              always contain the TYPE element, but it will
-              be an empty string if it's just a normal index.
-              If the index does not exist, we return undef.
+=over
+
+=item C<$table> - The name of the table the column is in.
+
+=item C<$column> - The name of the column.
 
 =back
 
+=item B<Returns>
 
-=head2 Deprecated Schema Information Methods
+An abstract column definition for that column. If the table or column 
+does not exist, we return C<undef>.
 
-These methods return info about the current Bugzilla database, for
-MySQL only.
+=back
 
-=over 4
+=item C<bz_index_info>
 
-=item C<bz_get_field_defs>
+=over
 
- Description: Returns a list of all the "bug" fields in Bugzilla. The list
-              contains hashes, with a 'name' key and a 'description' key.
- Params:      none
- Returns:     List of all the "bug" fields
+=item B<Description>
+
+Get abstract index definition.
+
+=item B<Params>
+
+=over
+
+=item C<$table> - The table the index is on.
+
+=item C<$index> - The name of the index.
+
+=back
+
+=item B<Returns>
+
+An abstract index definition for that index, always in hashref format. 
+The hashref will always contain the C<TYPE> element, but it will
+be an empty string if it's just a normal index.
+
+If the index does not exist, we return C<undef>.
+
+=back
 
 =back
 
@@ -1567,27 +2092,22 @@ MySQL only.
 These methods deal with the starting and stopping of transactions 
 in the database.
 
-=over 4
+=over
 
 =item C<bz_start_transaction>
 
- Description: Starts a transaction if supported by the database being used
- Params:      none
- Returns:     none
+Starts a transaction if supported by the database being used. Returns nothing
+and takes no parameters.
 
 =item C<bz_commit_transaction>
 
- Description: Ends a transaction, commiting all changes, if supported by
-              the database being used
- Params:      none
- Returns:     none
+Ends a transaction, commiting all changes, if supported by the database 
+being used. Returns nothing and takes no parameters.
 
 =item C<bz_rollback_transaction>
 
- Description: Ends a transaction, rolling back all changes, if supported by
-              the database being used
- Params:      none
- Returns:     none
+Ends a transaction, rolling back all changes, if supported by the database 
+being used. Returns nothing and takes no parameters.
 
 =back
 
@@ -1597,18 +2117,40 @@ in the database.
 Methods in this class are intended to be used by subclasses to help them
 with their functions.
 
-=over 4
+=over
 
 =item C<db_new>
 
- Description: Constructor
- Params:      $dsn = database connection string
-              $user = username used to log in to the database
-              $pass = password used to log in to the database
-              $attributes = set of attributes for DB connection (optional)
- Returns:     new instance of the DB class
- Note:        the name of this constructor is not new, as that would make
-              our check for implementation of new() by derived class useles.
+=over
+
+=item B<Description>
+
+Constructor
+
+=item B<Params>
+
+=over
+
+=item C<$dsn> - database connection string
+
+=item C<$user> - username used to log in to the database
+
+=item C<$pass> - password used to log in to the database
+
+=item C<\%attributes> - set of attributes for DB connection (optional)
+
+=back
+
+=item B<Returns>
+
+A new instance of the DB class
+
+=item B<Note>
+
+The name of this constructor is not C<new>, as that would make
+our check for implementation of C<new> by derived class useless.
+
+=back
 
 =back
 
@@ -1617,6 +2159,4 @@ with their functions.
 
 L<DBI>
 
-L<Bugzilla::Constants> - The C<DB_MODULE> constant.
-
-=cut
+L<Bugzilla::Constants/DB_MODULE>