--- name: "Pod::Coverage" section: "3pm" platform: "linux" package: "perl-pod-coverage" version: "0.23-6" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Pod::Coverage" --- # Pod::Coverage(3pm) Checks if the documentation of a module is comprehensive ## NAME Pod::Coverage - Checks if the documentation of a module is comprehensive ## SYNOPSIS ``` # 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. They'd hate it even more if their computer tattled on them, but maybe they'll be even more thankful in the long run. 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:\ \# 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 - 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. - $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 ## AUTHORS Richard Clamp \ Michael Stevens \ some contributions from David Cantrell \ ## 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.