Bug 784072: Use Pod::Coverage to make sure that all subroutines are documented

r=wurblzap a=LpSolit

diff --git a/t/011pod.t b/t/011pod.t
index c638dbcdedf0d1b2568e1ec8cd6e4eeb949b1752..7b9d0ee13e5ba984274a81aa8e523b51f344cce1 100644 (file)
--- a/t/011pod.t
+++ b/t/011pod.t
@@ -16,8 +16,32 @@ use lib 't';
 
 use Support::Files;
 use Pod::Checker;
+use Pod::Coverage;
 
-use Test::More tests => scalar(@Support::Files::testitems);
+use Test::More tests => scalar(@Support::Files::testitems)
+                        + scalar(@Support::Files::module_files);
+
+# These methods do not need to be documented by default.
+use constant DEFAULT_WHITELIST => qr/^(?:new|new_from_list|check|run_create_validators)$/;
+
+# These subroutines do not need to be documented, generally because
+# you shouldn't call them yourself. No need to include subroutines
+# of the form _foo(); they are already treated as private.
+use constant SUB_WHITELIST => (
+    'Bugzilla::Flag'     => qr/^(?:(force_)?retarget|force_cleanup)$/,
+    'Bugzilla::FlagType' => qr/^sqlify_criteria$/,
+);
+
+# These modules do not need to be documented, generally because they
+# are subclasses of another module which already has all the relevant
+# documentation. Partial names are allowed.
+use constant MODULE_WHITELIST => qw(
+    Bugzilla::Auth::Login::
+    Bugzilla::Auth::Persist::
+    Bugzilla::Auth::Verify::
+    Bugzilla::BugUrl::
+    Bugzilla::Config::
+);
 
 # Capture the TESTOUT from Test::More or Test::Builder for printing errors.
 # This will handle verbosity for us automatically.
@@ -48,4 +72,49 @@ foreach my $file (@testitems) {
     }
 }
 
+my %sub_whitelist = SUB_WHITELIST;
+my @module_files = sort @Support::Files::module_files;
+
+foreach my $file (@module_files) {
+    my $module = $file;
+    $module =~ s/\.pm$//;
+    $module =~ s#/#::#g;
+
+    my @whitelist = (DEFAULT_WHITELIST);
+    push(@whitelist, $sub_whitelist{$module}) if $sub_whitelist{$module};
+
+    # XXX Once all methods are correctly documented, nonwhitespace should
+    # be set to 1.
+    my $cover = Pod::Coverage->new(package => $module, nonwhitespace => 0,
+                                   trustme => \@whitelist);
+    my $coverage = $cover->coverage;
+    my $reason = $cover->why_unrated;
+
+    if (defined $coverage) {
+        if ($coverage == 1) {
+            ok(1, "$file has POD for all methods");
+        }
+        else {
+            ok(0, "$file POD coverage is " . sprintf("%u%%", 100 * $coverage) .
+                  ". Undocumented methods: " . join(', ', $cover->uncovered));
+        }
+    }
+    # This error is thrown when the module couldn't be loaded due to
+    # a missing dependency.
+    elsif ($reason eq "no public symbols defined") {
+        ok(1, "$file cannot be loaded");
+    }
+    elsif ($reason eq "couldn't find pod") {
+        if (grep { $module =~ /^\Q$_\E/ } MODULE_WHITELIST) {
+            ok(1, "$file does not contain any POD (whitelisted)");
+        }
+        else {
+            ok(0, "$file POD coverage is 0%");
+        }
+    }
+    else {
+        ok(0, "$file: $reason");
+    }
+}
+
 exit 0;

diff --git a/t/Support/Files.pm b/t/Support/Files.pm
index 1a8e6ee371bcdc3e67dad6d14d476e1678c19987..4b629785265e81c8990075ea4a94129a78bae965 100644 (file)
--- a/t/Support/Files.pm
+++ b/t/Support/Files.pm
@@ -42,6 +42,7 @@ foreach $currentfile (@files) {
     if (isTestingFile($currentfile)) {
         push(@testitems,$currentfile);
     }
+    push(@module_files, $currentfile) if $currentfile =~ /\.pm$/;
 }