view release on metacpan or  search on metacpan

lib/Test/CPAN/Health/Check/PODCoverage.pm  view on Meta::CPAN

package Test::CPAN::Health::Check::PODCoverage;

use strict;
use warnings;
use autodie qw(:all);

use Carp qw(croak carp);
use File::Spec;
use Readonly;
use Params::Validate::Strict qw(validate_strict);

use parent 'Test::CPAN::Health::Check';

our $VERSION = '0.1.0';

Readonly::Scalar my $SCORE_PASS  => 90;   # >= this -> pass
Readonly::Scalar my $SCORE_WARN  => 50;   # >= this -> warn; below -> fail

# Subs that are never expected to have their own POD section.
Readonly::Hash my %EXEMPT_SUBS => map { $_ => 1 } qw(
	DESTROY AUTOLOAD BEGIN END INIT CHECK UNITCHECK import unimport
);

=head1 NAME

Test::CPAN::Health::Check::PODCoverage - Check that all public methods have POD

=head1 SYNOPSIS

    use Test::CPAN::Health::Check::PODCoverage;

    my $check  = Test::CPAN::Health::Check::PODCoverage->new;
    my $result = $check->run($dist);

    printf "%s: %s\n", $result->status, $result->summary;

=head1 DESCRIPTION

Parses each C<.pm> file under C<lib/> to identify public subroutines (those
not prefixed with C<_> and not in the exempt set: DESTROY, AUTOLOAD, BEGIN,
END, etc.) and checks whether each one appears as a C<=head2>, C<=head3>, or
C<=head4> entry in the file's POD.

Score = (documented_subs / total_public_subs) * 100, averaged across all
files.  Status thresholds: pass E<ge> 90, warn E<ge> 50, fail otherwise.

=head1 LIMITATIONS

=over 4

=item * Documentation inherited from a parent class is not counted -- each
file is analysed in isolation.

=item * Only C<=head2>/C<=head3>/C<=head4> headings are matched against sub
names; C<=item> entries are not counted.

=item * Generated or XS subs not visible in the C<.pm> source are not counted.

=back

=cut

sub id          { return 'pod_coverage'                                          }
sub name        { return 'POD Coverage'                                          }
sub description { return 'Checks that all public methods are documented in POD'  }
sub weight      { return 5                                                       }
sub category    { return 'quality'                                               }

=head2 run

=head3 PURPOSE

Compute the fraction of public subroutines that have a corresponding POD
heading across all C<.pm> files in the distribution.

=head3 API SPECIFICATION

=head4 INPUT

  dist     Test::CPAN::Health::Distribution  required
  context  Hashref                           optional