Pod::Coverage(3)

💖 NAME 💖

Hey bestie! This is Pod::Coverage(3) from the User Contributed Perl Documentation, and it's the manual for Pod::Coverage — the module that checks if the documentation of a module is comprehensive. No cap, it's giving "your code has lore, but did you write it down?" energy. ✨

🎀 SYNOPSIS 🎀

Here's the vibe in code form, exactly as the page serves it:

         # in the beginnning...
         perl -MPod::Coverage=Pod::Coverage -e666

         # all in one invocation
         use Pod::Coverage package => 'Fishy';

         # straight OO
         use Pod::Coverage;
         my $pc = Pod::Coverage->new(package => 'Pod::Coverage');
         print "We rock!" if $pc->coverage == 1;

🌸 DESCRIPTION 🌸

Developers hate writing documentation — like, hate hate. They'd hate it even more if their computer snitched on them, but maybe they'll be even more thankful in the long run. And even if not, perlmodstyle tells you to, so you must obey. 😭

This module provides a mechanism for determining if the pod for a given module is comprehensive.

It expects to find either a =head(n>1) or an =item block documenting a subroutine.

Consider this imaginary Foo.pm:

        # an imaginary Foo.pm
        package Foo;

        =item foo

        The foo sub

        = cut

        sub foo {}
        sub bar {}

        1;
        __END__

In this example Foo::foo is covered, but Foo::bar is not, so the Foo package is only 50% (0.5) covered. 💅

💅 Methods 💅

Ok bestie, here's the method menu. 🫶

Pod::Coverage->new(package => $package)

Creates a new Pod::Coverage object. 🫶

• package — the name of the package to analyse
• private — an array of regexen which define what symbols are regarded as private (and so need not be documented). Defaults to:

[ qr/^_/,
           qr/^(un)?import$/, qr/^DESTROY$/, qr/^AUTOLOAD$/, qr/^bootstrap$/,
                   qr/^(TIE( SCALAR | ARRAY | HASH | HANDLE ) |
                        FETCH | STORE | UNTIE | FETCHSIZE | STORESIZE |
                        POP | PUSH | SHIFT | UNSHIFT | SPLICE | DELETE |
                        EXISTS | EXTEND | CLEAR | FIRSTKEY | NEXTKEY | PRINT |
           PRINTF |
                        WRITE | READLINE | GETC | READ | CLOSE | BINMODE | OPEN
           |
                        EOF | FILENO | SEEK | TELL | SCALAR )$/x,
                   qr/^( MODIFY | FETCH )_( REF | SCALAR | ARRAY | HASH | CODE
           |
                                            GLOB | FORMAT | IO )_ATTRIBUTES$/x,
                   qr/^CLONE(_SKIP)?$/, ]

This should cover all the usual magical methods for tie()d objects, attributes, generally all the methods that are typically not called by a user, but instead being used internally by perl.

• also_private — items are appended to the private list
• trustme — an array of regexen which define what symbols you just want us to assume are properly documented even if we can't find any docs for them
• If pod_from is supplied, that file is parsed for the documentation, rather than using Pod::Find
• If nonwhitespace is supplied, then only POD sections which have non-whitespace characters will count towards being documented.

$object->coverage

Gives the coverage as a value in the range 0 to 1.

$object->why_unrated

$object->coverage may return undef, to indicate that it was unable to deduce coverage for a package. If this happens you should be able to check why_unrated to get a useful excuse. Lowkey handy, ngl. 😭

$object->naked/$object->uncovered

Returns a list of uncovered routines, will implicitly call coverage if it's not already been called.

Note, private and 'trustme' identifiers will be skipped.

$object->covered

Returns a list of covered routines, will implicitly call coverage if it's not previously been called.

As with naked, private and 'trustme' identifiers will be skipped.

🐞 Debugging support 🐞

In order to allow internals debugging, while allowing the optimiser to do its thang, Pod::Coverage uses constant subs to define how it traces.

Use them like so:

        sub Pod::Coverage::TRACE_ALL () { 1 }
        use Pod::Coverage;

Supported constants are:

• TRACE_ALL — Trace everything.

Well that's all there is so far, are you glad you came? 😭

🌈 Inheritance interface 🌈

These abstract methods while functional in Pod::Coverage may make your life easier if you want to extend Pod::Coverage to fit your house style more closely.

NOTE: Please consider this interface as in a state of flux until this comment goes away.

$object->_CvGV($symbol)

Return the GV for the coderef supplied. Used by _get_syms to identify locally defined code.

You probably won't need to override this one.

$object->_get_syms($package)

return a list of symbols to check for from the specified packahe

_get_pods

Extract pod markers from the currently active package.

Return an arrayref or undef on fail.

_private_check($symbol)

return true if the symbol should be considered private

_trustme_check($symbol)

return true if the symbol is a 'trustme' symbol

💀 BUGS 💀

Due to the method used to identify documented subroutines Pod::Coverage may completely miss your house style and declare your code undocumented. Patches and/or failing tests welcome.

⭐ TODO ⭐

• Widen the rules for identifying documentation
• Improve the code coverage of the test suite. Devel::Cover rocks so hard.

🦋 SEE ALSO 🦋

• Test::More
• Devel::Cover

iykyk. 🦋

👑 AUTHORS 👑

• Richard Clamp <richardc@unixbeard.net>
• Michael Stevens <mstevens@etla.org>
• some contributions from David Cantrell <david@cantrell.org.uk>

💜 COPYRIGHT 💜

Copyright (c) 2001, 2003, 2004, 2006, 2007, 2009 Richard Clamp, Michael Stevens. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Periodt. 💜

✨ That's the whole page, bestie! It's from perl v5.42.0, dated 2020-10-28, for Pod::Coverage(3) — mwah! 💋