What is embedded documentation in Perl?

Perl allows multiple types of documentation, one of them being embedded documentation. With embedded documentation, users can embed text in code.

Plain Old Text

Plain old text (POD) is a markup language in which the embedded documentation is written. There are three types of paragraphs in POD:

• Ordinary Paragraph:
  Usual formatting codes can be used here to bold, italicize, etc., the text.
• Verbatim Paragraph:
  This is used for text that does not need special formatting.
• Command Paragraph:
  This is used for special treatment for the whole text using commands.

Declaration

The start of the embedded text is declared with the keyword =head1. The end is declared with the keyword =cut.

Syntax

=head1 Syntax example 
Write text to be embedded here.
=cut

Examples of supported commands are:

=pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=head4 Heading Text
=over indentlevel
=item stuff
=back
=begin format
=end format
=for format text...
=encoding type
=cut

Code

The following code snippet shows an example of the use of embedded documentation.