pod::coverage::trustpod(3) [centos man page]

Pod::Coverage::TrustPod(3)				User Contributed Perl Documentation				Pod::Coverage::TrustPod(3)

NAME

       Pod::Coverage::TrustPod - allow a module's pod to contain Pod::Coverage hints

VERSION

       version 0.100002

DESCRIPTION

       This is a Pod::Coverage subclass (actually, a subclass of Pod::Coverage::CountParents) that allows the POD itself to declare certain symbol
       names trusted.

       Here is a sample Perl module:

	 package Foo::Bar;

	 =head1 NAME

	 Foo::Bar - a bar at which fooes like to drink

	 =head1 METHODS

	 =head2 fee

	 returns the bar tab

	 =cut

	 sub fee { ... }

	 =head2 fie

	 scoffs at bar tab

	 =cut

	 sub fie { ... }

	 sub foo { ... }

	 =begin Pod::Coverage

	   foo

	 =end Pod::Coverage

	 =cut

       This file would report full coverage, because any non-empty lines inside a block of POD targeted to Pod::Coverage are treated as "trustme"
       patterns.  Leading and trailing whitespace is stripped and the remainder is treated as a regular expression anchored at both ends.

       Remember, anywhere you could use "=begin" and "=end" as above, you could instead write:

	 =for Pod::Coverage foo

AUTHOR

       Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2012 by Ricardo SIGNES.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

perl v5.16.3							    2012-04-21						Pod::Coverage::TrustPod(3)

Pod::Coverage(3pm)					User Contributed Perl Documentation					Pod::Coverage(3pm)

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 <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.

perl v5.14.2							    2012-02-07							Pod::Coverage(3pm)