Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Major documentation overhaul (Pau Amma).

With a few changes from me where the original documentation was confusing,
outdated or just wrong.
  • Loading branch information...
commit 04ad3fe03b3dc7b443c80d3738ff05a802d9e3b1 1 parent a1bb2d4
@pjcj authored
View
2  docs/TODO
@@ -58,3 +58,5 @@
- Examples.
- Document cpancover options.
- Pod in private modules.
+ - Developer documentation.
+ - Better DB API docs (including writing?).
View
203 lib/Devel/Cover.pm
@@ -681,7 +681,7 @@ Devel::Cover: Oops, it looks like something went wrong writing the coverage.
It's possible that more bad things may happen but we'll try to
carry on anyway as if nothing happened. At a minimum you'll
probably find that you are missing coverage. If you're
- interrested, the problem was:
+ interested, the problem was:
$@
@@ -1315,66 +1315,73 @@ If you want to get coverage for a program:
=head1 DESCRIPTION
-This module provides code coverage metrics for Perl. Code coverage
-metrics describe how thoroughly tests exercise code. By using
-Devel::Cover you can discover areas of code not exercised by your tests
-and determine which tests to create to increase coverage. Code coverage
-can be considered as an indirect measure of quality.
-
-I consider this software to have an alpha status. By that I mean that I
-reserve the right to alter the interface in a backwards incompatible manner
-without incrementing the major version number. I specifically do not mean
-that this software is full of bugs or missing key features. Although I'm
-making no guarantees on that front either. In short, if you are looking for
-code coverage software for Perl, you have probably come to the end of your
-search. For more of my opinions on this subject, see
-http://pjcj.sytes.net/notes/2007/03/14#alpha
-
-Code coverage data are collected using a pluggable runops function which
-counts how many times each op is executed. These data are then mapped
-back to reality using the B compiler modules. There is also a statement
-profiling facility which needs a better backend to be really useful.
-This release also includes an experimental mode which replaces ops
-instead of using a pluggable runops function. This provides a nice
-speed increase, but needs better testing before it becomes the default.
-You probably don't care about any of this.
-
-The F<cover> program can be used to generate coverage reports.
-
-Statement, branch, condition, subroutine, pod and time coverage information is
-reported. Statement coverage data should be reasonable, although there may be
-some statements which are not reported. Branch and condition coverage data
-should be mostly accurate too, although not always what one might initially
-expect. Subroutine coverage should be as accurate as statement coverage. Pod
-coverage comes from L<Pod::Coverage>. If L<Pod::Coverage::CountParents> is
-available it will be used instead. Coverage data for path coverage are not yet
-collected.
-
-The F<gcov2perl> program can be used to convert gcov files to
-C<Devel::Cover> databases.
-
-You may find that the results don't match your expectations. I would
-imagine that at least one of them is wrong.
-
-The most appropriate mailing list on which to discuss this module would
-be perl-qa. Discussion has migrated there from perl-qa-metrics which is
-now defunct. See L<http://lists.perl.org/list/perl-qa.html>.
+This module provides code coverage metrics for Perl. Code coverage metrics
+describe how thoroughly tests exercise code. By using Devel::Cover you can
+discover areas of code not exercised by your tests and determine which tests
+to create to increase coverage. Code coverage can be considered as an
+indirect measure of quality.
+
+Although it is still being developed, Devel::Cover is now quite stable and
+provides many of the features to be expected in a useful coverage tool.
+
+Statement, branch, condition, subroutine, and pod coverage information is
+reported. Statement coverage data should be reasonable. Branch and condition
+coverage data should be mostly accurate too, although not always what one
+might initially expect. Subroutine coverage should be as accurate as
+statement coverage. Pod coverage comes from L<Pod::Coverage>. If
+L<Pod::Coverage::CountParents> is available it will be used instead. Coverage
+data for other criteria are not yet collected.
+
+The F<cover> program can be used to generate coverage reports. Devel::Cover
+ships with a number of different reports including various types of HTML
+output, textual reports, a report to display missing coverage in the same
+format as compilation errors and a report to display coverage information
+within the Vim editor.
+
+It is possible to add annotations to reports, for example you could add a
+column to an HTML report showing who last changed a line, as determined by git
+blame. Some annotation modules are shipped with Devel::Cover and you can
+easily create your own.
+
+The F<gcov2perl> program can be used to convert gcov files to C<Devel::Cover>
+databases. This allows you to display your C or XS code coverage together
+with your Perl coverage, or to use any of the Devel::Cvoer reports to display
+your C coverage data.
+
+You may find that the coverage results don't match your expectations. This
+could be due to a bug in Devel::Cover, but code coverage can be unintuitive to
+newcomers, and especially so with Perl, so you may want to reconsider your
+expectations as well.
+
+Code coverage data are collected by replacing perl ops with functions which
+count how many times the ops are executed. These data are then mapped back to
+reality using the B compiler modules. There is also a statement profiling
+facility which should not be relied on. For proper profiling use
+Devel::NYTProf. Previous versions of Devel::Cover collected coverage data by
+replacing perl's runops function. It is still possible to switch to that mode
+of operation, but this now gets little testing and will probably be removed
+soon. You probably don't care about any of this.
+
+The most appropriate mailing list on which to discuss this module would be
+perl-qa. Discussion has migrated there from perl-qa-metrics which is now
+defunct. See L<http://lists.perl.org/list/perl-qa.html>.
The Devel::Cover repository can be found at
L<http://github.com/pjcj/Devel--Cover>.
-=head1 REQUIREMENTS
+=head1 REQUIREMENTS AND RECOMMENDED MODULES
+
+=head2 REQUIREMENTS
=over
=item * Perl 5.6.1 or greater. Perl 5.8.8 or greater is recommended.
-Perl 5.7.0 is unsupported. Perl 5.8.8 or greater is recommended. Perl
-5.8.7 has problems and may crash. Whilst Perl 5.6 should mostly work
-you will probably miss out on coverage information which would be
-available using a more modern version and will likely run into bugs in
-perl. Different versions of perl may give slightly different results
-due to changes in the op tree.
+Perl 5.7 is unsupported. Perl 5.8.8 or greater is recommended. Perl 5.8.7
+has problems and may crash. Whilst Perl 5.6 should mostly work you will
+probably miss out on coverage information which would be available using a
+more modern version and will likely run into bugs in perl. Different versions
+of perl may give slightly different results due to changes in the op tree.
=item * The ability to compile XS extensions.
@@ -1388,21 +1395,24 @@ that the appropriate tools are installed.
Both are in the core in Perl 5.8.0 and above.
-=item * L<Template> and L<PPI::HTML> or L<Perl::Tidy>
+=head2 OPTIONAL MODULES
+
+=item * L<Template>, and either L<PPI::HTML> or L<Perl::Tidy>
-if you want syntax highlighted HTML reports.
+Needed if you want syntax highlighted HTML reports.
-=item * L<Pod::Coverage>
+=item * L<Pod::Coverage> (0.06 or above) or L<Pod::Coverage::CountParents>
-if you want Pod coverage.
+One is needed if you want Pod coverage. If L<Pod::Coverage::CountParents> is
+installed, it is preferred.
=item * L<Test::More>
-in order to run the tests
+Required if you want to run Devel::Cover's own tests.
=item * L<Test::Warn>
-in order to run some of the tests
+Some of Devel::Cover's own tests require it.
=item * L<Test::Differences>
@@ -1410,6 +1420,14 @@ if the tests fail and you would like nice output telling you why.
=back
+=head2 Use with mod_perl
+
+By adding C<use Devel::Cover;> to your mod_perl startup script, you should be
+able to collect coverage information when running under mod_perl. You can
+also add any options you need at this point. I would suggest adding this as
+early as possible in your startup script in order to collect as much coverage
+information as possible.
+
=head1 OPTIONS
-blib - "use blib" and ignore files matching \bt/ (default true
@@ -1435,32 +1453,39 @@ if the tests fail and you would like nice output telling you why.
=head2 More on Coverage Options
You can specify options to some coverage criteria. At the moment only pod
-coverage takes any options. These are the parameters which are passed into the
-Pod::Coverage constructor. The extra options are separated by dashes, and you
-may specify as many as you wish. For example, to specify that all subroutines
-containing xx are private, call Devel::Cover with the option
+coverage takes any options. These are the parameters which are passed into
+the Pod::Coverage constructor. The extra options are separated by dashes, and
+you may specify as many as you wish. For example, to specify that all
+subroutines containing xx are private, call Devel::Cover with the option
-coverage,pod-also_private-xx.
=head1 SELECTING FILES TO COVER
-You may select which files you want covered using the select, ignore and inc
-options. The system works as follows:
+You may select the files for which you want to collect coverage data using the
+select, ignore and inc options. The system uses the following procedure to
+decide whether a file will be included in coverage reports:
+
+=over
+
+=item * If the file matches a RE given as a select option, it will be
+included.
-Any file matching a RE given as a select option is selected.
+=item * Otherwise, if it matches a RE given as an ignore option, it won't be
+included.
-Otherwise, any file matching a RE given as an ignore option is ignored.
+=item * Otherwise, if it is in one of the inc directories, it won't be
+included.
-Otherwise, any file in one of the inc directories is ignored.
+=item * Otherwise, it will be included.
-Otherwise the file is selected.
+=back
You may add to the REs to select by using +select, or you may reset the
-selections using -select. The same principle applies to the REs to
-ignore.
+selections using -select. The same principle applies to the REs to ignore.
-The inc directories are initially populated with the contents of the
-@INC array at the time Devel::Cover was built. You may reset these
-directories using -inc, or add to them using +inc.
+The inc directories are initially populated with the contents of the @INC
+array at the time Devel::Cover was built. You may reset these directories
+using -inc, or add to them using +inc.
Although these options take regular expressions, you should not enclose the RE
within // or any other quoting characters.
@@ -1468,14 +1493,16 @@ within // or any other quoting characters.
=head1 ENVIRONMENT
The -silent option is turned on when Devel::Cover is invoked via
-$HARNESS_PERL_SWITCHES or $PERL5OPT. Devel::Cover tries to do the right
-thing when $MOD_PERL is set. $DEVEL_COVER_OPTIONS is appended to any
-options passed into Devel::Cover.
+$HARNESS_PERL_SWITCHES or $PERL5OPT. Devel::Cover tries to do the right thing
+when $MOD_PERL is set. $DEVEL_COVER_OPTIONS is appended to any options passed
+into Devel::Cover.
When running Devel::Cover's own test suite, $DEVEL_COVER_DEBUG turns on
-debugging information, $DEVEL_COVER_GOLDEN_VERSION overrides
-Devel::Cover's own idea of which golden results it should test against,
-and $DEVEL_COVER_NO_COVERAGE runs the tests without collecting coverage.
+debugging information, $DEVEL_COVER_GOLDEN_VERSION overrides Devel::Cover's
+own idea of which golden results it should test against, and
+$DEVEL_COVER_NO_COVERAGE runs the tests without collecting coverage. The
+environment variables described in this paragraph are of interest to
+Devel::Cover maintainers only.
=head1 ACKNOWLEDGEMENTS
@@ -1545,14 +1572,6 @@ Modules used by Devel::Cover while gathering coverage:
=back
-=head2 mod_perl
-
-By adding C<use Devel::Cover;> to your mod_perl startup script, you
-should be able to collect coverage information when running under
-mod_perl. You can also add any options you need at this point. I would
-suggest adding this as early as possible in your startup script in order
-to collect as much coverage information as possible.
-
=head2 Redefined subroutines
If you redefine a subroutine you may find that the original subroutine is not
@@ -1563,15 +1582,17 @@ CV. Hints, tips or patches to resolve this will be gladly accepted.
Almost certainly.
-See the BUGS file. And the TODO file.
+See the BUGS file, the TODO file and the bug trackers at
+https://rt.cpan.org/Public/Dist/Display.html?Name=Devel-Cover and
+https://github.com/pjcj/Devel--Cover/issues?sort=created&direction=desc&state=open
=head1 LICENCE
-Copyright 2001-2011, Paul Johnson (pjcj@cpan.org)
+Copyright 2001-2012, Paul Johnson (pjcj@cpan.org)
This software is free. It is licensed under the same terms as Perl itself.
-The latest version of this software should be available from my homepage:
-http://www.pjcj.net
+The latest version of this software should be available on CPAN and from my
+homepage: http://www.pjcj.net/.
=cut
View
2  lib/Devel/Cover/Annotation/Git.pm
@@ -136,7 +136,7 @@ Devel::Cover::Annotation::Git - Annotate with git information
=head1 SYNOPSIS
- cover -report xxx -annotation git
+ cover -report text -annotation git # Or any other report type
=head1 DESCRIPTION
View
2  lib/Devel/Cover/Annotation/Random.pm
@@ -86,7 +86,7 @@ Devel::Cover::Annotation::Random - Example annotation for formatters
=head1 SYNOPSIS
- cover -report xxx -annotation random -count 3
+ cover -report text -annotation random -count 3 # Or any other report type
=head1 DESCRIPTION
View
4 lib/Devel/Cover/Annotation/Svk.pm
@@ -51,7 +51,7 @@ sub new
while (<$c>)
{
chomp;
- s{^\Q$self->{depotbase}\E/}{};
+ s|^\Q$self->{depotbase}\E/||;
next unless -f $_;
open my $f, $_ or warn "cover: Can't open $_: $!\n", next;
@@ -158,7 +158,7 @@ Devel::Cover::Annotation::Svk - Annotate with svk information
=head1 SYNOPSIS
- cover -report xxx -annotation svk
+ cover -report text -annotation svk # Or any other report type
=head1 DESCRIPTION
View
41 lib/Devel/Cover/DB.pm
@@ -973,10 +973,6 @@ Devel::Cover::DB - Code coverage metrics for Perl
This module provides access to a database of code coverage information.
-=head1 SEE ALSO
-
- Devel::Cover
-
=head1 METHODS
=head2 new
@@ -1009,13 +1005,26 @@ data may be accessed.
}
}
-Data for different criteria will be in different formats, so that will
-need special handling, but I'll deal with that when we have the data for
-different criteria.
+Data for different criteria will be in different formats, so that will need
+special handling. This is not yet documented so your best bet for now is to
+look at some of the simpler reports and/or the source.
+
+The methods in the above example are actually aliases for methods in
+Devel::Cover::DB::Base (the base class for all Devel::Cover::DB::* classes):
+
+=over
+
+=item * Devel::Cover::DB::Base->values
-If you don't want to remember all the method names, use values() instead
-of files(), criteria() and locations() and get() instead of file(),
-criterion() and location().
+Aliased to Devel::Cover::DB::Cover->files, Devel::Cover::DB::File->criteria,
+Devel::Cover::DB::Criterion->locations, and Devel::Cover::DB::Location->data
+
+=item * Devel::Cover::DB::Base->get
+
+Aliased to Devel::Cover::DB::Cover->file, Devel::Cover::DB::File->criteriom,
+Devel::Cover::DB::Criterion->location, and Devel::Cover::DB::Location->datum
+
+=back
Instead of calling $file->criterion("x") you can also call $file->x.
@@ -1023,8 +1032,16 @@ Instead of calling $file->criterion("x") you can also call $file->x.
my $valid = $db->is_valid;
-Returns true iff the db is valid. (Actually there is one too many fs there, but
-that's what it should do.)
+Returns true if $db is valid (or looks valid, the function is too lax).
+
+=head1 SEE ALSO
+
+ Devel::Cover
+ Devel::Cover::DB::Base
+ Devel::Cover::DB::Cover
+ Devel::Cover::DB::File
+ Devel::Cover::DB::Criterion
+ Devel::Cover::DB::Location
=head1 BUGS
View
1  lib/Devel/Cover/DB/Digests.pm
@@ -113,6 +113,7 @@ This module stores digests for Devel::Cover::DB.
=head1 SEE ALSO
Devel::Cover
+ Devel::Cover::DB
=head1 METHODS
View
2  lib/Devel/Cover/DB/IO/Storable.pm
@@ -74,7 +74,7 @@ Contructs the IO object.
my $data = $io->read($file);
-Returns a perl data structure representingthe data read from $file.
+Returns a perl data structure representing the data read from $file.
=head2 write
View
3  lib/Devel/Cover/DB/Structure.pm
@@ -389,7 +389,7 @@ __END__
=head1 NAME
-Devel::Cover::DB::Structure - Code coverage metrics for Perl
+Devel::Cover::DB::Structure - Internal: abstract structure of a source file
=head1 SYNOPSIS
@@ -400,6 +400,7 @@ Devel::Cover::DB::Structure - Code coverage metrics for Perl
=head1 SEE ALSO
Devel::Cover
+ Devel::Cover::DB
=head1 METHODS
View
2  lib/Devel/Cover/Op.pm
@@ -98,7 +98,7 @@ Devel::Cover::Op - B::Concise with coverage data
=head1 DESCRIPTION
This module works as if calling B::Concise but also outputs coverage
-information. It's primary purpose is to aid in the development of Devel::Cover.
+information. Its primary purpose is to aid in the development of Devel::Cover.
See comments in Cover.xs (especially set_conditional()) to aid in interpreting
the output.
View
4 lib/Devel/Cover/Report/Html.pm
@@ -25,9 +25,7 @@ statistics
=head1 SYNOPSIS
- use Devel::Cover::Report::Html;
-
- Devel::Cover::Report::Html->report($db, $options);
+ cover -report html
=head1 DESCRIPTION
View
4 lib/Devel/Cover/Report/Html_basic.pm
@@ -772,9 +772,7 @@ statistics
=head1 SYNOPSIS
- use Devel::Cover::Report::Html_basic;
-
- Devel::Cover::Report::Html_basic->report($db, $options);
+ cover -report html_basic
=head1 DESCRIPTION
View
18 lib/Devel/Cover/Report/Html_minimal.pm
@@ -742,9 +742,7 @@ statistics
=head1 SYNOPSIS
- use Devel::Cover::Report::Html_minimal;
-
- Devel::Cover::Report::Html_minimal->report($db, $options);
+ cover -report html_minimal
=head1 DESCRIPTION
@@ -769,26 +767,26 @@ directory.
=item pod
-Includes POD (and blank lines) in the file report. This is on by default. It
+Includes POD (and blank lines) in the file report. This is on by default. It
may be turned off with -nopod.
=item data
-Includes text after the C<__DATA__> or C<__END__> tokens in the file report. By
+Includes text after the C<__DATA__> or C<__END__> tokens in the file report. By
default, this text is trimmed.
Note: If your POD is after an C<__END__>, you have to specify 'data' to include
-it, not 'pod'. The 'pod' option only applies to POD before the C<__END__>.
+it, not 'pod'. The 'pod' option only applies to POD before the C<__END__>.
=item unified
-Generates a "unified" report for each file. The detailed data that normally
-appears in the auxilliary reports (branch, condition, etc.) is placed in the
-file report, and the auxilliarry reports are not generated.
+Generates a "unified" report for each file. The detailed data that normally
+appears in the auxiliary reports (branch, condition, etc.) are placed in the
+file report, and the auxiliary reports are not generated.
=item summarytitle
-Specify the tile of the summary. The default is "Coverage Summary".
+Specify the title of the summary. The default is "Coverage Summary".
=back
View
4 lib/Devel/Cover/Report/Html_subtle.pm
@@ -706,9 +706,7 @@ statistics
=head1 SYNOPSIS
- use Devel::Cover::Report::Html_subtle;
-
- Devel::Cover::Report::Html_subtle->report($db, $options);
+ cover -report html_subtle
=head1 DESCRIPTION
View
6 lib/Devel/Cover/Report/Text2.pm
@@ -167,14 +167,12 @@ __END__
=head1 NAME
-Devel::Cover::Report::Text - Backend for textual reporting of coverage
+Devel::Cover::Report::Test2 - Backend for textual reporting of coverage
statistics
=head1 SYNOPSIS
- use Devel::Cover::Report::Text;
-
- Devel::Cover::Report::Text->report($db, $options);
+ cover -report text2
=head1 DESCRIPTION
Please sign in to comment.
Something went wrong with that request. Please try again.