Perl has a mechanism for intermixing documentation with source code. While itís expecting the beginning of a new
statement, if the compiler encounters a line that begins with an equal sign and a word, like this
Then that text and all remaining text up through and including a line beginning with "=cut" will be ignored. The
format of the intervening text is described in perlpod.
=head1 Here There Be Pods!
(Emphasis by me).
POD is only allowed at statement boundaries. This is probably because it's very confusing to have a huge piece of text between the beginning and the end of a statement, and thus would make reading the code much harder.
- links to (nearly) everything that is Perl 6.