Bug 284352: Break Bugzilla::DB code/docs into sections

Patch By Max Kanat-Alexander <mkanat@kerio.com> r=travis, a=myk

webtools/bugzilla/Bugzilla/DB.pm

@@ -125,6 +125,10 @@ sub PopGlobalSQLState() {
 
 # MODERN CODE BELOW
 
+#####################################################################
+# Connection Methods
+#####################################################################
+
 sub connect_shadow {
     die "Tried to connect to non-existent shadowdb" unless Param('shadowdb');
 
@@ -207,12 +211,22 @@ sub sql_position {
     return "POSITION($fragment IN $text)";
 }
 
+#####################################################################
+# General Info Methods
+#####################################################################
+
 # XXX - Needs to be documented.
 sub bz_server_version {
     my ($self) = @_;
     return $self->get_info(18); # SQL_DBMS_VER
 }
 
+sub bz_last_key {
+    my ($self, $table, $column) = @_;
+
+    return $self->last_insert_id($db_name, undef, $table, $column);
+}
+
 sub bz_get_field_defs {
     my ($self) = @_;
 
@@ -233,6 +247,10 @@ sub bz_get_field_defs {
     return(@fields);
 }
 
+#####################################################################
+# Schema Modification Methods
+#####################################################################
+
 # XXX - Need to make this cross-db compatible
 # XXX - This shouldn't print stuff to stdout
 sub bz_add_field ($$$) {
@@ -332,6 +350,10 @@ sub bz_rename_field ($$$) {
     }
 }
 
+#####################################################################
+# Schema Information Methods
+#####################################################################
+
 # XXX - Needs to be made cross-db compatible.
 sub bz_get_field_def ($$) {
     my ($self, $table, $field) = @_;
@@ -385,11 +407,9 @@ sub bz_table_exists ($) {
    return $exists;
 }
 
-sub bz_last_key {
-    my ($self, $table, $column) = @_;
-
-    return $self->last_insert_id($db_name, undef, $table, $column);
-}
+#####################################################################
+# Transaction Methods
+#####################################################################
 
 sub bz_start_transaction {
     my ($self) = @_;
@@ -431,6 +451,10 @@ sub bz_rollback_transaction {
     }
 }
 
+#####################################################################
+# Subclass Helpers
+#####################################################################
+
 sub db_new {
     my ($class, $dsn, $user, $pass, $attributes) = @_;
 
@@ -598,7 +622,7 @@ should not be called from anywhere else.
 
 =back
 
-=head2 Methods
+=head1 ABSTRACT METHODS
 
 Note: Methods which can be implemented generically for all DBs are implemented in
 this module. If needed, they can be overriden with DB specific code.
@@ -714,6 +738,20 @@ 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
 
+=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.
+
+=over 4
+
 =item C<bz_last_key>
 
  Description: Returns the last serial number, usually from a previous INSERT.
@@ -726,6 +764,12 @@ formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
               $column = name of column containing serial data type (scalar)
  Returns:     Last inserted ID (scalar)
 
+=head2 Schema Modification Methods
+
+These methods modify the current Bugzilla schema.
+
+=over 4
+
 =item C<bz_add_field>
 
  Description: Adds a new column to a table in the database. Prints out
@@ -771,6 +815,12 @@ formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
               $newname = the new name of the column
  Returns:     none
 
+=head2 Schema Information Methods
+
+These methods return info about the current Bugzilla database schema.
+
+=over 4
+
 =item C<bz_get_field_defs>
 
  Description: Returns a list of all the "bug" fields in Bugzilla. The list
@@ -825,6 +875,13 @@ formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
                        of (scalar)
  Returns:     A true value if the table exists, a false value otherwise.
 
+=head2 Transaction Methods
+
+These methods deal with the starting and stopping of transactions 
+in the database.
+
+=over 4
+
 =item C<bz_start_transaction>
 
  Description: Starts a transaction if supported by the database being used
@@ -845,6 +902,13 @@ formatted SQL command have prefix C<sql_>. All other methods have prefix C<bz_>.
  Params:      none
  Returns:     none
 
+=head1 SUBCLASS HELPERS
+
+Methods in this class are intended to be used by subclasses to help them
+with their functions.
+
+=over 4
+
 =item C<db_new>
 
  Description: Constructor