From: Dylan Hardison <dylan@hardison.net>
Date: Tue, 1 Nov 2022 08:15:08 +0000 (-0700)
Subject: Fix pod tests by adding documentation (#124)
X-Git-Tag: bugzilla-5.2~48
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=dcb2cd97c2d0e99306fd2bb66e8c7b29f73ab13a;p=thirdparty%2Fbugzilla.git

Fix pod tests by adding documentation (#124)

* Fix pod tests by adding documentation

Co-authored-by: Dave Miller <github@justdave.net>
---

diff --git a/Bugzilla/DB.pm b/Bugzilla/DB.pm
index cbef41447c..f4590474cf 100644
--- a/Bugzilla/DB.pm
+++ b/Bugzilla/DB.pm
@@ -33,6 +33,7 @@ use Storable qw(dclone);
 
 has [qw(dsn user pass attrs)] => (is => 'ro', required => 1,);
 
+
 has 'qi' => (is => 'lazy');
 
 sub _build_qi {
@@ -2409,6 +2410,32 @@ Formatted SQL for the C<IN> operator.
 
 =back
 
+=head1 ATTRIBUTES
+
+=over 4
+
+=item C<dsn>
+
+The data source name for the database. This is a string that is passed to
+the DBI to connect to the database. It is usually of the form:
+
+  dbi:DriverName:database_name
+
+=item C<user>
+
+The user name to use when connecting to the database.
+
+=item C<pass>
+
+The password to use when connecting to the database.
+
+=item C<attrs>
+
+A hashref of attributes to pass to the DBI when connecting to the database.
+It is usually used to set the C<RaiseError> and C<PrintError> attributes,
+but can be used to set any attribute that the DBI supports.
+
+=back
 
 =head1 IMPLEMENTED METHODS
 
diff --git a/Bugzilla/DB/Mysql.pm b/Bugzilla/DB/Mysql.pm
index ad5fe383b9..c01415f20a 100644
--- a/Bugzilla/DB/Mysql.pm
+++ b/Bugzilla/DB/Mysql.pm
@@ -1151,48 +1151,120 @@ sub _bz_build_schema_from_disk {
 
 1;
 
-=head1 B<Methods in need of POD>
+=head1 METHODS
 
-=over
+=head2 BUILDARGS
 
-=item sql_date_format
+This method is called by L<Moo> when creating a new object. It turns the flat
+named arguments from C<new()> and puts them into the C<dsn>, C<user>, C<pass>,
+and C<attr> attributes.
 
-=item bz_explain
+=head2 on_dbi_connected
 
-=item bz_last_key
+This method is called by L<DBI> when a connection is established. It sets various connection-specific attributes
+which are nessessary for the database to function correctly. Because the database can be reconnected to 
+any required session variables must be set here.
 
-=item sql_position
+Undocumented methods: utf8_charset, utf8_collate, default_row_format'
 
-=item sql_fulltext_search
+=head2 utf8_charset
 
-=item sql_iposition
+Returns the name of the charset to use for utf8 columns.
+This comes from the C<Bugzilla-E<gt>params-E<gt>{utf8}> parameter.
+It can be either true, false, or utf8mb4
 
-=item bz_enum_initial_values
+=head2 utf8_collate
 
-=item sql_group_by
+Returns the name of the collation to use for utf8 columns.
+When C<utf8_charset> is C<utf8mb4> this is C<utf8mb4_unicode_520_ci>.
+Otherwise it is C<utf8_general_ci>.
 
-=item sql_limit
+=head2 default_row_format
 
-=item sql_not_regexp
+Returns the default row format to use for tables.
+When C<utf8_charset> is C<utf8mb4> this is C<DYNAMIC> for most tables,
+and C<COMPRESSED> for several table that benefit from compression.
 
-=item sql_string_concat
+When C<utf8_charset> is C<utf8> this is C<COMPACT> for all tables.
 
-=item sql_date_math
+=head2 sql_date_format
 
-=item sql_to_days
+Returns the SQL date format string for the current database.
 
-=item bz_check_server_version
+=head2 bz_explain
 
-=item sql_from_days
+Returns the EXPLAIN output for the given SQL statement.
 
-=item sql_regexp
+=head2 bz_last_key
 
-=item sql_istring
+Returns the last auto-increment key generated by the database.
 
-=item sql_group_concat
+=head2 sql_position
 
-=item bz_setup_database
+Returns the SQL position function for the current database.
 
-=item bz_db_is_utf8
+=head2 sql_fulltext_search
+
+Returns the SQL fulltext search function for the current database.
+
+=head2 sql_iposition
+
+Returns the SQL position function for the current database, but
+case-insensitive.
+
+=head2 bz_enum_initial_values
+
+Returns the initial values for an ENUM column.
+
+=head2 sql_group_by
+
+Returns the SQL GROUP BY clause for the current database.
+
+=head2 sql_limit
+
+Returns the SQL LIMIT clause for the current database.
+
+=head2 sql_not_regexp
+
+Returns the SQL NOT REGEXP operator for the current database.
+
+=head2 sql_string_concat
+
+Returns the SQL string concatenation operator for the current database.
+
+=head2 sql_date_math
+
+Returns the SQL date math operator for the current database.
+
+=head2 sql_to_days
+
+Returns the SQL to_days function for the current database.
+
+=head2 bz_check_server_version
+
+Returns true if the database server version is at least the given
+
+=head2 sql_from_days
+
+Returns the SQL from_days function for the current database.
+
+=head2 sql_regexp
+
+Returns the SQL REGEXP operator for the current database.
+
+=head2 sql_istring
+
+Returns the SQL string case-insensitive operator for the current database.
+
+=head2 sql_group_concat
+
+Returns the SQL GROUP_CONCAT function for the current database.
+
+=head2 bz_setup_database
+
+Sets up the database for use with Bugzilla.
+
+=head2 bz_db_is_utf8
+
+Returns true if the database is using UTF-8.
 
-=back
diff --git a/Bugzilla/DB/QuoteIdentifier.pm b/Bugzilla/DB/QuoteIdentifier.pm
index b3957d163f..dfca191019 100644
--- a/Bugzilla/DB/QuoteIdentifier.pm
+++ b/Bugzilla/DB/QuoteIdentifier.pm
@@ -67,5 +67,44 @@ as in the case of MySQL 8, formerly unreserved keywords can become reserved.
 This module provides a shortcut for quoting identifiers in strings by way of overloading a hash
 so that we can easily call C<quote_identifier> inside double-quoted strings.
 
+=head1 METHODS
+
+=head2 TIEHASH
+
+This class can be used as a tied hash, which is only done to allow quoting identifiers inside double-quoted strings.
+
+Exmaple:
+
+    my $qi = Bugzilla->dbh->qi;
+    my $sql = "SELECT $qi->{bug_id} FROM $qi->{bugs}";
+
+=head2 FETCH
+
+Returns the quoted identifier for the given key, this just calls C<quote_identifier> on the database handle.
+
+=head2 FIRSTKEY
+
+This returns nothing, as this tied hash has no keys or values.
+
+=head2 FIRSTVALUE
+
+This returns nothing, as this tied hash has no keys or values.
+
+=head2 EXISTS
+
+This always returns true, as this tied hash has no keys or values but technically every key exists.
+
+=head2 DELETE
+
+This always returns true, as this tied hash has no keys or values but technically every key can be deleted.
+
+=head2 db
+
+This is a weak reference to the database handle that is used to quote identifiers.
+
+=head1 SEE ALSO
+
+L<Bugzilla::DB::Schema>
+
 =cut
 
diff --git a/Bugzilla/DB/Schema.pm b/Bugzilla/DB/Schema.pm
index 928e92ac72..f8a0c88b66 100644
--- a/Bugzilla/DB/Schema.pm
+++ b/Bugzilla/DB/Schema.pm
@@ -1747,10 +1747,21 @@ 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 BUILD {
+
+=item C<BUILD>
+
+This method exists to bridge between the old way of doing things (calling C<_initialize>)
+and the Moo way of doing things. Moo will call this method when you call C<new> on a class,
+and it will throw an error if called on the base class. This is because the base class is abstract.
+
+=cut
+
   my $self   = shift;
   my $class  = ref($self) || $self;
 
@@ -1768,13 +1779,40 @@ sub BUILD {
 # instead setting it in _initialize() if it isn't already passed in.
 has 'abstract_schema' => ( init_arg => '_abstract_schema', is => 'rw' );
 
+=item C<abstract_schema>
+
+Returns the abstract schema for this database. It is initialized in C<_initialize>.
+
+=cut
+
 # this could also be lazy, but it is also set in _initialize()
 has 'schema' => (init_arg =>undef, is => 'rw');
 
+=item C<schema>
+
+Returns the schema for this database. It is initialized in C<_initialize>
+and cannot be passed in to C<new>.
+
+=cut
+
 has 'db_specific' => (init_arg => undef, is => 'rw');
 
+=item C<db_specific>
+
+Returns the DB-specific schema for this database. It is initialized in C<_initialize>
+and cannot be passed in to C<new>.
+
+=cut
+
 has 'db' => (is => 'ro', weak_ref => 1, required => 1);
 
+=item C<db>
+
+Returns the L<Bugzilla::DB> object that this schema is associated with.
+This is a weak reference, so it will be C<undef> if the L<Bugzilla::DB>
+object has been destroyed.
+
+=cut
 
 #--------------------------------------------------------------------------
 sub _initialize {
diff --git a/Bugzilla/DB/Sqlite.pm b/Bugzilla/DB/Sqlite.pm
index cdf0d13e7f..6d7da47292 100644
--- a/Bugzilla/DB/Sqlite.pm
+++ b/Bugzilla/DB/Sqlite.pm
@@ -344,4 +344,8 @@ For interface details see L<Bugzilla::DB> and L<DBI>.
 
 =item bz_setup_database
 
+=item BUILDARGS
+
+=item on_dbi_connected
+
 =back
diff --git a/Bugzilla/Util.pm b/Bugzilla/Util.pm
index ae85ff389c..ce0644f9b3 100644
--- a/Bugzilla/Util.pm
+++ b/Bugzilla/Util.pm
@@ -1313,18 +1313,44 @@ if Bugzilla is currently using the shadowdb or not. Used like:
 
 =back
 
-=head1 B<Methods in need of POD>
-
 =over
 
-=item do_ssl_redirect_if_required
+=item C<write_text($filename, $content)>
+
+Writes $content to $filename. The content will be encoded as UTF-8. Returns 1 if
+the atomic write was successful, 0 otherwise. C<$!> will be set to the error
+from C<rename()>.
+
+=item C<read_text($filename)>
+
+Reads the contents of $filename and returns it as a string. The string will be
+decoded as UTF-8.
+
+=item C<is_ipv4>
+
+Returns true if the given IP address is an IPv4 address.
+
+=item C<is_ipv6>
+
+Returns true if the given IP address is an IPv6 address.
+
+=item C<do_ssl_redirect_if_required>
+
+If Bugzilla is configured to redirect all HTTP requests to HTTPS, this function
+will redirect the user to the HTTPS version of the current page. It will not do
+anything if the user is already on HTTPS, or if there is no C<sslbase> parameter
+set.
 
-=item validate_time
+=item C<validate_time>
 
-=item is_ipv4
+Validates a time string. Returns true or false depending on whether the time
+string is valid.
 
-=item is_ipv6
+=item C<display_value>
 
-=item display_value
+Returns the display value for a given field and value. This value comes from the
+value_descs template variable. The value_descs variable is set in the template
+file C<global/value-descs.none.tmpl>. This is used for localizing Bugzilla to
+other languages.
 
 =back
diff --git a/t/002goodperl.t b/t/002goodperl.t
index b61c0ad853..130f8de75d 100644
--- a/t/002goodperl.t
+++ b/t/002goodperl.t
@@ -86,6 +86,8 @@ foreach my $file (@testitems) {
 }
 
 foreach my $file (@testitems) {
+  my $enables_strict_re = qr/^\s*use\s+(?:strict|Moo)\s*;/;
+  my $enables_warnings_re = qr/^\s*use\s+(?:warnings|Moo)\s*;/;
   my $found_use_perl     = 0;
   my $found_use_strict   = 0;
   my $found_use_warnings = 0;
@@ -98,8 +100,8 @@ foreach my $file (@testitems) {
   }
   while (my $file_line = <FILE>) {
     $found_use_perl     = 1 if $file_line =~ m/^\s*use 5.10.1/;
-    $found_use_strict   = 1 if $file_line =~ m/^\s*use strict/;
-    $found_use_warnings = 1 if $file_line =~ m/^\s*use warnings/;
+    $found_use_strict   = 1 if $file_line =~ $enables_strict_re;
+    $found_use_warnings = 1 if $file_line =~ $enables_warnings_re;
     last if ($found_use_perl && $found_use_strict && $found_use_warnings);
   }
   close(FILE);