NAME

App::perl::distrolint::Check::Pod - check that every Perl source file contains documentation

DESCRIPTION

This checks that Perl source code files contain at least one block of Pod.

Unit tests (named *.t) and build-time generated source files (*.PL) are exempt from this check. Files in the examples/ directory are also skipped.

Additionally checks that each of the following =head1 sections appear:

   =head1 NAME
   =head1 DESCRIPTION
   =head1 AUTHOR

Additional checks are applied to the contents of various =head sections.

Checks on NAME

After a =head1 NAME there should be exactly one paragraph, and its content should match NAME - text, where NAME should match the module name implied by the file's path, optionally wrapped in C<...> formatting.

Checks on FUNCTIONS and METHODS

For every =head2 inside =head1 FUNCTIONS or =head1 METHODS, the text is checked to ensure it is a bareword function/method name, optionally followed by other clarifying text after whitespace.

After every =head2 the next paragraph must be a verbatim paragraph, presumed to contain the function's minsynopsis code. The contents of this are also checked, to see that the first line looks like an example calling the named function or method, that ends in a semicolon.

The function name can optionally be preceeded by a variable assignment to indicate the return value ($var = ... or ($list, $of, @vars) = ...), optionally prefixed with my. It can optionally be preceeded by a variable containing the invocant name and a method call arrow ($var->...). It can optionally be followed by any other text in parentheses, to indicate the arguments passed. It can optionally use an await expression, used to indicate it is a Future-returning asynchronous function or method.

E.g.

   funcname;
   funcname(@args);
   $self->methodname(@args);
   $result = funcname(args, here);
   my ($return, $values) = Some::Package->methodname(some, more, args);
   my $response = await $client->call;

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>