Test::Synopsis is an (author) test module to find .pm or .pod files
under your lib directory and then make sure the example snippet
code in your SYNOPSIS section passes the perl compile check.
Note that this module only checks the perl syntax (by wrapping the
code with sub) and doesnt actually run the code.
Suppose you have the following POD in your module.
Awesome::Template - My awesome template
my $template = Awesome::Template->new;
An user of your module would try copy-paste this synopsis code and
find that this code doesnt compile because theres a typo in your
variable name $tempalte. Test::Synopsis will catch that error
before you ship it.
Sometimes you might want to put some undeclared variables in your
print Dumper($scalar, \@array, \%hash);
This assumes these variables like $scalar are defined elsewhere in
module users code, but Test::Synopsis, by default, will complain that
these variables are not declared:
Global symbol "$scalar" requires explicit package name at ...
In this case, you can add the following POD sequence elsewhere in your POD:
no strict vars
Or more explicitly,
my($scalar, @array, %hash);
Test::Synopsis will find these =for blocks and these statements are
prepended before your SYNOPSIS code when being evaluated, so those
variable name errors will go away, without adding unnecessary bits in
SYNOPSIS which might confuse users.