NAME

    Test::Pod::CoverageChange - Test Perl files for POD coverage and syntax
    changes

SYNOPSIS

     use Test::Pod::CoverageChange qw(pod_coverage_syntax_ok);
    
     pod_coverage_syntax_ok('lib', {
         MyModule::Bar => 3,  ## expected to have 3 naked subs
         MyModule::Foo => 10, ## expected to have 10 naked subs
         MyModule::Baz => 1,  ## expected to have 1 naked subs
         MyModule::Qux => 5,  ## expected to have 5 naked subs
     }, [
         We::Ignore::ThisModule,
         We::Also::Ignore::This::Module
     ],[
         'a_sub_name_to_ignore'
         qr/regexes are also acceptable/
     ]);

DESCRIPTION

    Test::Pod::CoverageChange is a helper combining Test::Pod::Coverage and
    Pod::Checker to test for both POD coverage and syntax changes for a
    module distribution at once, via a single call to
    "pod_coverage_syntax_ok".

    Possible results

      * passes if the file has no POD syntax or coverage error.

      * fails if latest changes increased/decreased numbers of naked subs
      for the packages that have allowed naked subs.

      * fails if a package allowed to have naked subs has 100% POD
      coverage.

      * fails if a file in a given path has POD syntax error or has no POD.

    Ignores packages that passed as ignored package in the
    c<$ignored_package> argument into the pod_coverage_syntax_ok sub.

 pod_coverage_syntax_ok

    Checks all the modules under a given directory against POD coverage and
    POD syntax

      * $path - path or arrayref of directories to check (recursively)

      example: ['lib', 'other directory'] | 'lib'

      * $allowed_naked_packages - hashref of number of allowed naked subs,
      keyed by package name (optional)

      example: {Package1 => 2, Package2 => 1, Package3 => 10}

      * $ignored_packages - arrayref of packages that will be ignored in
      the checks (optional)

      example: ['MyPackage1', 'MyPackage2', 'MyPackage3']

      * $ignored_subs - arrayref of subnames or regexes that will be
      ignored in the checks (optional)

      example: ['a_sub_name', qr/a regex/]

 _check_pod_coverage

    Checks POD coverage for all the modules that exist under the given
    directory. Passes the $allowed_naked_packages to
    "_check_allowed_naked_packages" in Test::Pod::CoverageChange. Ignores
    the packages in the $ignored_packages parameter.

      * $path - path or arrayref of directories to check (recursively)

      * $allowed_naked_packages - hashref of number of allowed naked subs,
      keyed by package name (optional)

      * $ignored_packages - arrayref of packages that will be ignored in
      the checks (optional)

 _check_pod_syntax

    Check POD syntax for all the modules that exist under the given
    directory.

      * $path - path or arrayref of directories to check (recursively)

      * $ignored_packages - arrayref of packages that will be ignored in
      the checks (optional)

 _check_allowed_naked_packages

    Checks passed allowed_naked_packages against existing package files.

      * $allowed_naked_packages - hashref of number of allowed naked subs,
      keyed by package name (optional)

      * $ignored_packages - a list of packages that will be ignored in our
      checks, supports arrayref (optional)

    Possible results

      * todo fail if the numbers of existing naked subs are equal to passed
      value.

      * fails if the number of existing naked subs are not equal to the
      passed value.

      * fails if a package has 100% POD coverage and it passed as a
      $allowed_naked_package.

