From: Vincent Pit <vince@profvince.com>
Date: Sat, 24 Aug 2013 21:20:55 +0000 (-0300)
Subject: Make sure the POD headings are linkable
X-Git-Tag: v1.14~4
X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=d83358595540f8645467c2d1a2f658fa74b14c72;p=perl%2Fmodules%2FTest-Valgrind.git

Make sure the POD headings are linkable
---

diff --git a/lib/Test/Valgrind.pm b/lib/Test/Valgrind.pm
index d5ddb28..be57279 100644
--- a/lib/Test/Valgrind.pm
+++ b/lib/Test/Valgrind.pm
@@ -49,7 +49,9 @@ As such, it's complementary to the other very good leak detectors listed in the
 
 =head1 METHODS
 
-=head2 C<analyse [ %options ]>
+=head2 C<analyse>
+
+    Test::Valgrind->analyse(%options);
 
 Run a C<valgrind> analysis configured by C<%options> :
 
@@ -194,7 +196,9 @@ sub analyse {
  return $status;
 }
 
-=head2 C<import [ %options ]>
+=head2 C<import>
+
+    use Test::Valgrind %options;
 
 In the parent process, L</import> calls L</analyse> with the arguments it received itself - except that if no C<file> option was supplied, it tries to pick the first caller context that looks like a script.
 When the analysis ends, it exits with the status returned by the action (for the default TAP-generator action, it's the number of failed tests).
diff --git a/lib/Test/Valgrind/Action.pm b/lib/Test/Valgrind/Action.pm
index af23f09..23c3ae1 100644
--- a/lib/Test/Valgrind/Action.pm
+++ b/lib/Test/Valgrind/Action.pm
@@ -27,7 +27,9 @@ use base qw<Test::Valgrind::Component Test::Valgrind::Carp>;
 
 =head1 METHODS
 
-=head2 C<< new action => $action >>
+=head2 C<new>
+
+    my $tva = Test::Valgrind::Action->new(action => $action);
 
 Creates a new action object of type C<$action> by requiring and redispatching the method call to the module named C<$action> if it contains C<'::'> or to C<Test::Valgrind::Action::$action> otherwise.
 The class represented by C<$action> must inherit this class.
@@ -60,13 +62,17 @@ Indicates if the action wants C<valgrind> to run in suppression-generating mode
 
 sub do_suppressions { 0 }
 
-=head2 C<start $session>
+=head2 C<start>
+
+    $tva->start($session);
 
 Called when the C<$session> starts.
 
 Defaults to set L<Test::Valgrind::Component/started>.
 
-=head2 C<report $session, $report>
+=head2 C<report>
+
+    $tva->report($session, $report);
 
 Invoked each time the C<valgrind> process attached to the C<$session> spots an error.
 C<$report> is a L<Test::Valgrind::Report> object describing the error.
@@ -83,7 +89,9 @@ sub report {
  return;
 }
 
-=head2 C<abort $session, $msg>
+=head2 C<abort>
+
+    $tva->abort($session, $msg);
 
 Triggered when the C<$session> has to interrupt the action.
 
@@ -93,13 +101,17 @@ Defaults to croak.
 
 sub abort { $_[0]->_croak($_[2]) }
 
-=head2 C<finish $session>
+=head2 C<finish>
+
+    $tva->finish($session);
 
 Called when the C<$session> finishes.
 
 Defaults to clear L<Test::Valgrind::Component/started>.
 
-=head2 C<status $session>
+=head2 C<status>
+
+    $tva->status($session);
 
 Returns the status code corresponding to the last run of the action.
 
diff --git a/lib/Test/Valgrind/Action/Captor.pm b/lib/Test/Valgrind/Action/Captor.pm
index ad9dfbc..b354097 100644
--- a/lib/Test/Valgrind/Action/Captor.pm
+++ b/lib/Test/Valgrind/Action/Captor.pm
@@ -50,7 +50,10 @@ sub _dup_fh {
              or $_[0]->_croak('open(' . fileno($_[1]) . ", '$_[2]&', $fd): $!");
 }
 
-=head2 C<save_fh $from, $mode [, $to ]>
+=head2 C<save_fh>
+
+    $tva->save_fh($from, $mode);
+    $tva->save_fh($from, $mode, $to);
 
 Save the original filehandle C<$from> opened with mode C<$mode>, and redirect it to C<$to> if it's defined or to F</dev/null> otherwise.
 
@@ -78,6 +81,8 @@ sub save_fh {
 
 =head2 C<restore_all_fh>
 
+    $tva->restore_all_fh;
+
 Restore all the filehandles that were saved with L</save_fh> to their original state.
 
 The redirections aren't closed.
diff --git a/lib/Test/Valgrind/Action/Suppressions.pm b/lib/Test/Valgrind/Action/Suppressions.pm
index 1d86ca8..3c6cffe 100644
--- a/lib/Test/Valgrind/Action/Suppressions.pm
+++ b/lib/Test/Valgrind/Action/Suppressions.pm
@@ -27,7 +27,13 @@ use base qw<Test::Valgrind::Action Test::Valgrind::Action::Captor>;
 
 This class inherits L<Test::Valgrind::Action>.
 
-=head2 C<< new name => $name, target => $target, ... >>
+=head2 C<new>
+
+    my $tvas = Test::Valgrind::Action::Suppressions->new(
+     name   => $name,
+     target => $target,
+     %extra_args,
+    );
 
 Your usual constructor.
 
@@ -63,6 +69,8 @@ sub do_suppressions { 1 }
 
 =head2 C<name>
 
+    my $name = $tvas->name;
+
 Read-only accessor for the C<name> option.
 
 =cut
@@ -71,6 +79,8 @@ sub name   { $_[0]->{name} }
 
 =head2 C<target>
 
+    my $target = $tvas->target;
+
 Read-only accessor for the C<target> option.
 
 =cut
diff --git a/lib/Test/Valgrind/Action/Test.pm b/lib/Test/Valgrind/Action/Test.pm
index c479a67..971cbbf 100644
--- a/lib/Test/Valgrind/Action/Test.pm
+++ b/lib/Test/Valgrind/Action/Test.pm
@@ -29,7 +29,13 @@ use base qw<Test::Valgrind::Action Test::Valgrind::Action::Captor>;
 
 This class inherits L<Test::Valgrind::Action> and L<Test::Valgrind::Action::Captor>.
 
-=head2 C<< new diag => $diag, extra_tests => $extra_tests, ... >>
+=head2 C<new>
+
+    my $tvat = Test::Valgrind::Action::Test->new(
+     diag        => $diag,
+     extra_tests => $extra_tests,
+     %extra_args,
+    );
 
 Your usual constructor.
 
@@ -60,6 +66,8 @@ sub new {
 
 =head2 C<diag>
 
+    my $diag = $tvat->diag;
+
 Read-only accessor for the C<diag> option.
 
 =cut
@@ -68,6 +76,8 @@ sub diag { $_[0]->{diag} }
 
 =head2 C<kinds>
 
+    my @kinds = $tvat->kinds;
+
 Returns the list of all the monitored report kinds.
 
 =cut
diff --git a/lib/Test/Valgrind/Command.pm b/lib/Test/Valgrind/Command.pm
index 0f87b2a..3e0dcbc 100644
--- a/lib/Test/Valgrind/Command.pm
+++ b/lib/Test/Valgrind/Command.pm
@@ -28,7 +28,12 @@ use base qw<Test::Valgrind::Carp>;
 
 =head1 METHODS
 
-=head2 C<< new command => $command, args => \@args >>
+=head2 C<new>
+
+    my $tvc = Test::Valgrind::Command->new(
+     command => $command,
+     args    => \@args,
+    );
 
 Creates a new command object of type C<$command> by requiring and redispatching the method call to the module named C<$command> if it contains C<'::'> or to C<Test::Valgrind::Command::$command> otherwise.
 The class represented by C<$command> must inherit this class.
@@ -68,7 +73,9 @@ Defaults to return C<undef>, which skips suppression generation.
 
 sub new_trainer { }
 
-=head2 C<args $session>
+=head2 C<args>
+
+    my @args = $tvc->args($session);
 
 Returns the list of command-specific arguments that are to be passed to C<valgrind>.
 
@@ -78,7 +85,9 @@ Defaults to return the contents of the C<args> option.
 
 sub args { @{$_[0]->{args} || []} }
 
-=head2 C<env $session>
+=head2 C<env>
+
+    my $env = $tvc->env($session);
 
 This event is called in scalar context before the command is ran, and the returned value goes out of scope when the analysis ends.
 It's useful for e.g. setting up C<%ENV> for the child process by returning an L<Env::Sanctify> object, hence the name.
@@ -89,7 +98,9 @@ Defaults to void.
 
 sub env { }
 
-=head2 C<suppressions_tag $session>
+=head2 C<suppressions_tag>
+
+    my $tag = $tvc->suppressions_tag($session);
 
 Returns a identifier that will be used to pick up the right suppressions for running the command, or C<undef> to indicate that no special suppressions are needed.
 
@@ -99,7 +110,9 @@ This method must be implemented when subclassing.
 
 sub suppressions_tag;
 
-=head2 C<filter $session, $report>
+=head2 C<filter>
+
+    my $filtered_report = $tvc->filter($session, $report);
 
 The C<$session> calls this method after receiving a report from the tool and before forwarding it to the action.
 You can either return a mangled C<$report> (which does not need to be a clone of the original) or C<undef> if you want the action to ignore it completely.
diff --git a/lib/Test/Valgrind/Command/Aggregate.pm b/lib/Test/Valgrind/Command/Aggregate.pm
index 4b8647e..c8adec3 100644
--- a/lib/Test/Valgrind/Command/Aggregate.pm
+++ b/lib/Test/Valgrind/Command/Aggregate.pm
@@ -29,7 +29,12 @@ use base qw<Test::Valgrind::Command Test::Valgrind::Carp>;
 
 This class inherits L<Test::Valgrind::Command>.
 
-=head2 C<< new commands => \@commands, ... >>
+=head2 C<new>
+
+    my $tvca = Test::Valgrind::Command::Aggregate->new(
+     commands => \@commands,
+     %extra_args,
+    );
 
 =cut
 
@@ -60,6 +65,8 @@ sub new {
 
 =head2 C<commands>
 
+    my @commands = $tvca->commands;
+
 Read-only accessor for the C<commands> option.
 
 =cut
diff --git a/lib/Test/Valgrind/Command/Perl.pm b/lib/Test/Valgrind/Command/Perl.pm
index 79532c3..b701fec 100644
--- a/lib/Test/Valgrind/Command/Perl.pm
+++ b/lib/Test/Valgrind/Command/Perl.pm
@@ -32,7 +32,14 @@ use base qw<Test::Valgrind::Command Test::Valgrind::Carp>;
 
 This class inherits L<Test::Valgrind::Command>.
 
-=head2 C<< new perl => $^X, inc => \@INC, taint_mode => $taint_mode, ... >>
+=head2 C<new>
+
+    my $tvcp = Test::Valgrind::Command::Perl->new(
+     perl       => $^X,
+     inc        => \@INC,
+     taint_mode => $taint_mode,
+     %extra_args,
+    );
 
 The package constructor, which takes several options :
 
@@ -107,6 +114,8 @@ sub new_trainer {
 
 =head2 C<perl>
 
+    my $perl = $tvcp->perl;
+
 Read-only accessor for the C<perl> option.
 
 =cut
@@ -115,6 +124,8 @@ sub perl { $_[0]->{perl} }
 
 =head2 C<inc>
 
+    my @inc = $tvcp->inc;
+
 Read-only accessor for the C<inc> option.
 
 =cut
@@ -123,6 +134,8 @@ sub inc { @{$_[0]->{inc} || []} }
 
 =head2 C<taint_mode>
 
+    my $taint_mode = $tvcp->taint_mode;
+
 Read-only accessor for the C<taint_mode> option.
 
 =cut
@@ -138,7 +151,9 @@ sub args {
         $self->SUPER::args(@_);
 }
 
-=head2 C<env $session>
+=head2 C<env>
+
+    my $env = $tvcp->env($session);
 
 Returns an L<Env::Sanctify> object that sets the environment variables C<PERL_DESTRUCT_LEVEL> to C<3> and C<PERL_DL_NONLAZY> to C<1> during the run.
 
diff --git a/lib/Test/Valgrind/Command/PerlScript.pm b/lib/Test/Valgrind/Command/PerlScript.pm
index 602ca4c..7e77910 100644
--- a/lib/Test/Valgrind/Command/PerlScript.pm
+++ b/lib/Test/Valgrind/Command/PerlScript.pm
@@ -27,7 +27,13 @@ use base qw<Test::Valgrind::Command::Perl Test::Valgrind::Carp>;
 
 This class inherits L<Test::Valgrind::Command::Perl>.
 
-=head2 C<< new file => $file, [ taint_mode => $taint_mode ], ... >>
+=head2 C<new>
+
+    my $tvcps = Test::Valgrind::Command::PerlScript->new(
+     file       => $file,
+     taint_mode => $taint_mode,
+     %extra_args,
+    );
 
 The package constructor, which takes several options :
 
@@ -82,6 +88,8 @@ sub new_trainer { Test::Valgrind::Command::Perl->new_trainer }
 
 =head2 C<file>
 
+    my $file = $tvcps->file;
+
 Read-only accessor for the C<file> option.
 
 =cut
diff --git a/lib/Test/Valgrind/Component.pm b/lib/Test/Valgrind/Component.pm
index 9a7ba2b..739845f 100644
--- a/lib/Test/Valgrind/Component.pm
+++ b/lib/Test/Valgrind/Component.pm
@@ -29,6 +29,8 @@ use base qw<Test::Valgrind::Carp>;
 
 =head2 C<new>
 
+    my $tvc = Test::Valgrind::Component->new;
+
 Basic constructor.
 
 =cut
@@ -50,7 +52,9 @@ sub new {
  }, $class;
 }
 
-=head2 C<started [ $bool ]>
+=head2 C<started>
+
+    $tvc->started($bool);
 
 Specifies whether the component is running (C<1>), stopped (C<0>) or was never started (C<undef>).
 
@@ -60,6 +64,8 @@ sub started { @_ <= 1 ? $_[0]->{started} : ($_[0]->{started} = $_[1] ? 1 : 0) }
 
 =head2 C<start>
 
+    $tvc->start;
+
 Marks the component as started, and throws an exception if it was already.
 Returns its self object.
 
@@ -76,6 +82,8 @@ sub start {
 
 =head2 C<finish>
 
+    $tvc->finish;
+
 Marks the component as stopped, and throws an exception if it wasn't started.
 Returns its self object.
 
diff --git a/lib/Test/Valgrind/Parser.pm b/lib/Test/Valgrind/Parser.pm
index 46c7db8..10eee71 100644
--- a/lib/Test/Valgrind/Parser.pm
+++ b/lib/Test/Valgrind/Parser.pm
@@ -27,17 +27,23 @@ use base qw<Test::Valgrind::Component Test::Valgrind::Carp>;
 
 =head2 C<new>
 
+    my $tvp = Test::Valgrind::Parser->new;
+
 The parser constructor, called without arguments.
 
 Defaults to L<Test::Valgrind::Component/new>.
 
-=head2 C<start $session>
+=head2 C<start>
+
+    $tvp->start($session);
 
 Called when the C<$session> starts.
 
 Defaults to set L<Test::Valgrind::Component/started>.
 
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+    my @args = $tvp->args($session, $fh);
 
 Returns the list of parser-specific arguments that are to be passed to the C<valgrind> process spawned by the session C<$session> and whose output will be captured by the filehandle C<$fh>.
 
@@ -47,7 +53,9 @@ Defaults to the empty list.
 
 sub args { }
 
-=head2 C<parse $session, $fh>
+=head2 C<parse>
+
+    $tvp->parse($session, $fh);
 
 Parse the output of the C<valgrind> process attached to the session C<$session> received through the filehandle C<$fh>.
 
@@ -57,7 +65,9 @@ This method must be implemented when subclassing.
 
 sub parse;
 
-=head2 C<finish $session>
+=head2 C<finish>
+
+    $tvp->finish($session);
 
 Called when the C<$session> finishes.
 
diff --git a/lib/Test/Valgrind/Parser/Text.pm b/lib/Test/Valgrind/Parser/Text.pm
index 6939e14..f479537 100644
--- a/lib/Test/Valgrind/Parser/Text.pm
+++ b/lib/Test/Valgrind/Parser/Text.pm
@@ -25,7 +25,9 @@ use base qw<Test::Valgrind::Parser>;
 
 =head1 METHODS
 
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+    my @args = $tvp->args($session, $fh);
 
 Returns the arguments needed to tell C<valgrind> to print in text to the filehandle C<$fh>.
 
diff --git a/lib/Test/Valgrind/Parser/XML.pm b/lib/Test/Valgrind/Parser/XML.pm
index bc8a4ad..fae88b6 100644
--- a/lib/Test/Valgrind/Parser/XML.pm
+++ b/lib/Test/Valgrind/Parser/XML.pm
@@ -25,7 +25,9 @@ use base qw<Test::Valgrind::Parser>;
 
 =head1 METHODS
 
-=head2 C<args $session, $fh>
+=head2 C<args>
+
+    my @args = $tvp->args($session, $fh);
 
 Returns the arguments needed to tell C<valgrind> to print in XML to the filehandle C<$fh>.
 
diff --git a/lib/Test/Valgrind/Report.pm b/lib/Test/Valgrind/Report.pm
index 1192f72..b233b0d 100644
--- a/lib/Test/Valgrind/Report.pm
+++ b/lib/Test/Valgrind/Report.pm
@@ -27,7 +27,13 @@ The C<Diag> kind is reserved for diagnostics.
 
 use base qw<Test::Valgrind::Carp>;
 
-=head2 C<< new kind => $kind, id => $id, data => $data >>
+=head2 C<new>
+
+   my $tvr = Test::Valgrind::Report->new(
+    kind => $kind,
+    id   => $id,
+    data => $data,
+   );
 
 Your usual constructor.
 
@@ -73,7 +79,9 @@ sub new {
  }, $class;
 }
 
-=head2 C<< new_diag $data >>
+=head2 C<new_diag>
+
+    my $diag_report = Test::Valgrind::Report->new_diag($data);
 
 Constructs a report with kind C<'Diag'>, an auto-incremented identifier and the given C<$data>.
 
@@ -85,6 +93,8 @@ sub new_diag { shift->new(kind => 'Diag', id => ++$diag_id, data => $_[0]) }
 
 =head2 C<kind>
 
+    my $kind = $tvr->kind;
+
 Read-only accessor for the C<kind> option.
 
 =cut
@@ -93,6 +103,8 @@ sub kind { $_[0]->{kind} }
 
 =head2 C<id>
 
+    my $id = $tvr->id;
+
 Read-only accessor for the C<id> option.
 
 =cut
@@ -101,6 +113,8 @@ sub id { $_[0]->{id} }
 
 =head2 C<data>
 
+    my $data = $tvr->data;
+
 Read-only accessor for the C<data> option.
 
 =cut
@@ -109,6 +123,8 @@ sub data { $_[0]->{data} }
 
 =head2 C<is_diag>
 
+    $tvr->is_diag;
+
 Tells if a report has the C<'Diag'> kind, i.e. is a diagnostic.
 
 =cut
@@ -117,6 +133,8 @@ sub is_diag { $_[0]->kind eq 'Diag' }
 
 =head2 C<kinds>
 
+    my @kinds = $tvr->kinds;
+
 Returns the list of valid kinds for this report class.
 
 Defaults to C<'Diag'>.
@@ -125,7 +143,9 @@ Defaults to C<'Diag'>.
 
 sub kinds { 'Diag' }
 
-=head2 C<valid_kind $kind>
+=head2 C<valid_kind>
+
+    $tvr->valid_kind($kind);
 
 Tells whether C<$kind> is a valid kind for this report class.
 
diff --git a/lib/Test/Valgrind/Session.pm b/lib/Test/Valgrind/Session.pm
index 22a9129..7964761 100644
--- a/lib/Test/Valgrind/Session.pm
+++ b/lib/Test/Valgrind/Session.pm
@@ -34,7 +34,16 @@ use base qw<Test::Valgrind::Carp>;
 
 =head1 METHODS
 
-=head2 C<< new search_dirs => \@search_dirs, valgrind => [ $valgrind | \@valgrind ], min_version => $min_version, no_def_supp => $no_def_supp, extra_supps => \@extra_supps >>
+=head2 C<new>
+
+    my $tvs = Test::Valgrind::Session->new(
+     search_dirs => \@search_dirs,
+     valgrind    => $valgrind,  # One candidate
+     valgrind    => \@valgrind, # Several candidates
+     min_version => $min_version,
+     no_def_supp => $no_def_supp,
+     extra_supps => \@extra_supps,
+    );
 
 The package constructor, which takes several options :
 
@@ -130,10 +139,14 @@ sub new {
 
 =head2 C<valgrind>
 
+    my $valgrind_path = $tvs->valgrind;
+
 The path to the selected C<valgrind> executable.
 
 =head2 C<version>
 
+    my $valgrind_version = $tvs->version;
+
 The L<version> object associated to the selected C<valgrind>.
 
 =cut
@@ -149,6 +162,8 @@ sub version {
 
 =head2 C<no_def_supp>
 
+    my $no_def_supp = $tvs->no_def_supp;
+
 Read-only accessor for the C<no_def_supp> option.
 
 =cut
@@ -157,13 +172,21 @@ eval "sub $_ { \$_[0]->{$_} }" for qw<valgrind no_def_supp>;
 
 =head2 C<extra_supps>
 
+    my @extra_supps = $tvs->extra_supps;
+
 Read-only accessor for the C<extra_supps> option.
 
 =cut
 
 sub extra_supps { @{$_[0]->{extra_supps} || []} }
 
-=head2 C<< run action => $action, tool => $tool, command => $command >>
+=head2 C<run>
+
+    $tvs->run(
+     action  => $action,
+     tool    => $tool,
+     command => $command,
+    );
 
 Runs the command C<$command> through C<valgrind> with the tool C<$tool>, which will report to the action C<$action>.
 
@@ -358,6 +381,8 @@ sub def_supp_file {
 
 =head2 C<suppressions>
 
+    my @suppressions = $tvs->suppressions;
+
 Returns the list of all the suppressions that will be passed to C<valgrind>.
 Honors L</no_def_supp> and L</extra_supps>.
 
@@ -378,6 +403,12 @@ sub suppressions {
 
 =head2 C<start>
 
+    $tvs->start(
+     action  => $action,
+     tool    => $tool,
+     command => $command,
+    );
+
 Starts the action and tool associated to the current run.
 It's automatically called at the beginning of L</run>.
 
@@ -405,7 +436,9 @@ sub start {
  return;
 }
 
-=head2 C<abort $msg>
+=head2 C<abort>
+
+    $tvs->abort($msg);
 
 Forwards to C<< ->action->abort >> after unshifting the session object to the argument list.
 
@@ -417,7 +450,9 @@ sub abort {
  $self->action->abort($self, @_);
 }
 
-=head2 C<report $report>
+=head2 C<report>
+
+    $tvs->report($report);
 
 Forwards to C<< ->action->report >> after unshifting the session object to the argument list.
 
@@ -438,6 +473,8 @@ sub report {
 
 =head2 C<finish>
 
+    $tvs->finish;
+
 Finishes the action and tool associated to the current run.
 It's automatically called at the end of L</run>.
 
@@ -462,6 +499,8 @@ sub finish {
 
 =head2 C<status>
 
+    my $status = $tvs->status;
+
 Returns the status code of the last run of the session.
 
 =cut
diff --git a/lib/Test/Valgrind/Suppressions.pm b/lib/Test/Valgrind/Suppressions.pm
index ad27f6b..f522444 100644
--- a/lib/Test/Valgrind/Suppressions.pm
+++ b/lib/Test/Valgrind/Suppressions.pm
@@ -25,7 +25,13 @@ use base qw<Test::Valgrind::Carp>;
 
 =head1 METHODS
 
-=head2 C<< generate tool => $tool, command => $command, target => $target >>
+=head2 C<generate>
+
+    Test::Valgrind::Suppressions->generate(
+     tool    => $tool,
+     command => $command,
+     target  => $target,
+    );
 
 Generates suppressions for the command C<< $command->new_trainer >> and the tool C<< $tool->new_trainer >>, and writes them in the file specified by C<$target>.
 The action used behind the scenes is L<Test::Valgrind::Action::Suppressions>.
@@ -88,7 +94,12 @@ sub generate {
  return $status;
 }
 
-=head2 C<strip_tail $session, $suppression>
+=head2 C<strip_tail>
+
+    my $mangled_suppression = Test::Valgrind::Suppressions->strip_tail(
+     $session,
+     $suppression,
+    );
 
 Removes all wildcard frames at the end of the suppression.
 Moreover, C<'...'> is appended when C<valgrind> C<3.4.0> or higher is used.
@@ -111,7 +122,11 @@ sub strip_tail {
  $supp;
 }
 
-=head2 C<maybe_z_demangle $symbol>
+=head2 C<maybe_z_demangle>
+
+    my $demangled_symbol = Test::Valgrind::Suppressions->maybe_z_demangle(
+     $symbol,
+    );
 
 If C<$symbol> is Z-encoded as described in C<valgrind>'s F<include/pub_tool_redir.h>, extract and decode its function name part.
 Otherwise, C<$symbol> is returned as is.
diff --git a/lib/Test/Valgrind/Tool.pm b/lib/Test/Valgrind/Tool.pm
index 304cf72..4aea0fb 100644
--- a/lib/Test/Valgrind/Tool.pm
+++ b/lib/Test/Valgrind/Tool.pm
@@ -30,6 +30,8 @@ use base qw<Test::Valgrind::Component Test::Valgrind::Carp>;
 
 =head2 C<requires_version>
 
+    my $required_version = $tvt->requires_version;
+
 The minimum C<valgrind> version needed to run this tool.
 Defaults to C<3.1.0>.
 
@@ -37,7 +39,9 @@ Defaults to C<3.1.0>.
 
 sub requires_version { '3.1.0' }
 
-=head2 C<< new tool => $tool >>
+=head2 C<new>
+
+    my $tvt = Test::Valgrind::Tool->new(tool => $tool);
 
 Creates a new tool object of type C<$tool> by requiring and redispatching the method call to the module named C<$tool> if it contains C<'::'> or to C<Test::Valgrind::Tool::$tool> otherwise.
 The class represented by C<$tool> must inherit this class.
@@ -63,6 +67,8 @@ sub new {
 
 =head2 C<new_trainer>
 
+    my $tvt_train = Test::Valgrind::Tool->new_trainer;
+
 Creates a new tool object suitable for generating suppressions.
 
 Defaults to return C<undef>, which skips suppression generation.
@@ -71,7 +77,9 @@ Defaults to return C<undef>, which skips suppression generation.
 
 sub new_trainer { }
 
-=head2 C<parser_class $session>
+=head2 C<parser_class>
+
+    my $parser_class = $tvt->parser_class($session);
 
 Returns the class from which the parser for this tool output will be instanciated.
 
@@ -81,7 +89,9 @@ This method must be implemented when subclassing.
 
 sub parser_class;
 
-=head2 C<report_class $session>
+=head2 C<report_class>
+
+    my $report_class = $tvt->report_class($session);
 
 Returns the class in which suppression reports generated by this tool will be blessed.
 
@@ -91,7 +101,9 @@ This method must be implemented when subclassing.
 
 sub report_class;
 
-=head2 C<args $session>
+=head2 C<args>
+
+    my @args = $tvt->args($session);
 
 Returns the list of tool-specific arguments that are to be passed to C<valgrind>.
 All the suppression arguments are already handled by the session.
@@ -102,7 +114,9 @@ Defaults to the empty list.
 
 sub args { }
 
-=head2 C<suppressions_tag $session>
+=head2 C<suppressions_tag>
+
+    my $tag = $tvt->suppressions_tag($session);
 
 Returns a identifier that will be used to pick up the right suppressions for running the tool, or C<undef> to indicate that no special suppressions are needed.
 
@@ -112,13 +126,17 @@ This method must be implemented when subclassing.
 
 sub suppressions_tag;
 
-=head2 C<start $session>
+=head2 C<start>
+
+    $tvt->start($session);
 
 Called when the C<$session> starts.
 
 Defaults to set L<Test::Valgrind::Component/started>.
 
-=head2 C<filter $session, $report>
+=head2 C<filter>
+
+    my $filtered_report = $tvt->filter($session, $report);
 
 The C<$session> calls this method after receiving a report from the parser and before letting the command filter it.
 You can either return a mangled C<$report> (which does not need to be a clone of the original) or C<undef> if you want the action to ignore it completely.
@@ -129,7 +147,9 @@ Defaults to the identity function.
 
 sub filter { $_[2] }
 
-=head2 C<finish $session>
+=head2 C<finish>
+
+    $tvt->finish($session);
 
 Called when the C<$session> finishes.
 
diff --git a/lib/Test/Valgrind/Tool/memcheck.pm b/lib/Test/Valgrind/Tool/memcheck.pm
index 78236c7..1b1ad4b 100644
--- a/lib/Test/Valgrind/Tool/memcheck.pm
+++ b/lib/Test/Valgrind/Tool/memcheck.pm
@@ -29,13 +29,20 @@ This class inherits L<Test::Valgrind::Tool>.
 
 =head2 C<requires_version>
 
+    my $required_version = $tvt->requires_version;
+
 This tool requires C<valgrind> C<3.1.0>.
 
 =cut
 
 sub requires_version { '3.1.0' }
 
-=head2 C<< new callers => $callers, ... >>
+=head2 C<new>
+
+    my $tvtm = Test::Valgrind::Tool::memcheck->new(
+     callers => $callers,
+     %extra_args,
+    );
 
 Your usual constructor.
 
@@ -65,6 +72,8 @@ sub new_trainer { shift->new(callers => 50) }
 
 =head2 C<callers>
 
+    my $callers = $tvtm->callers;
+
 Read-only accessor for the C<callers> option.
 
 =cut
@@ -73,7 +82,9 @@ sub callers { $_[0]->{callers} }
 
 sub suppressions_tag { 'memcheck-' . $_[1]->version }
 
-=head2 C<parser_class $session>
+=head2 C<parser_class>
+
+    my $parser_class = $tvtm->parser_class($session);
 
 This tool uses a L<Test::Valgrind::Parser::XML::Twig> parser in analysis mode, and a L<Test::Valgrind::Parser::Suppressions::Text> parser in suppressions mode.
 
@@ -92,7 +103,9 @@ sub parser_class {
  return $class;
 }
 
-=head2 C<report_class $session>
+=head2 C<report_class>
+
+    my $report_class = $tvtm->report_class($session);
 
 This tool emits C<Test::Valgrind::Tool::memcheck::Report> object reports in analysis mode, and C<Test::Valgrind::Report::Suppressions> object reports in suppressions mode.