Learning Perl - Plain Old Documentation

When you write and program in any language it is good practice to document your code. Each language has its own way of doing this. In Perl, the most common way to document your code is through comments and POD, which stands for Plain Old Documentation.

POD is a simple way to write documentation in Perl scripts and modules. It allows you to embed documentation directly within your code, making it easier to maintain and understand. POD is designed to be easy to read and write, and it can be converted into various formats such as HTML and markdown.

POD is written in a simple markup language that uses special formatting characters to indicate headings, lists, and other elements. Here are some basic elements of POD. You can use the following table as a reference:

POD Element	Description
=head1	Top-level heading, used for the title of the document or major sections.
=head2	Second-level heading, used for subsections within a major section.
=head3	Third-level heading, used for further subsections.
=cut	Marks the end of the POD section, indicating that the rest of the file is code.
=over	Starts a list.
=item	Starts a new item in a list.
=back	Ends a list.
=pod	Starts a POD section, indicating that the following text is documentation.
=end	Ends a POD section, used to indicate the end of a specific POD block.
=encoding	Specifies the character encoding used in the POD document.

Today we will use the module we installed in the previous post, Module::Starter, to create a new module and then we will inspect the POD documentation that is generated. To do this, we will create a new module called Module::Test using the Module::Starter command line tool.

module-starter --module="Module::Test" --author="Your Name" --email="your email"

This command will create a new directory called Module-Test, cd into it and then ls to list the contents of the directory.

cd Module-Test
ls

Changes     MANIFEST    Makefile.PL README      ignore.txt  lib     t       xt

As you can see, the Module-Test directory contains several files and directories. The most important ones for our purpose are:

• lib/Module/Test.pm: This is the main module file where we will write our code and documentation.
• MANIFEST: This file lists all the files in the module, which is useful for distribution.
• Makefile.PL: This is a Perl script that defines how to build and install the module.
• README: This file contains basic information about the module, such as its purpose and how to use it.
• t/: This directory contains test files for the module, which we will cover in a future post.

Now that we have created the module structure, we can start exploring the generated files. The Module::Starter tool has created a basic structure for our module, including a lib/ directory where the module code will reside.

First lets look at the README file, which contains basic information about the module. It should look something like this:

Module-Test

The README is used to introduce the module and provide instructions on
how to install the module, any machine dependencies it may have (for
example C compilers and installed libraries) and any other information
that should be provided before the module is installed.

A README file is required for CPAN modules since CPAN extracts the README
file from a module distribution so that people browsing the archive
can use it to get an idea of the module's uses. It is usually a good idea
to provide version information here so that people can decide whether
fixes for the module are worth downloading.


INSTALLATION

To install this module, run the following commands:

    perl Makefile.PL
    make
    make test
    make install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc Module::Test

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        https://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Test

    Search CPAN
        https://metacpan.org/release/Module-Test


LICENSE AND COPYRIGHT

This software is Copyright (c) 2025 by LNATION.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

As you can see the README file provides basic information about the module, including installation instructions, support and documentation links, and license information. It is a good practice to keep this file updated with relevant information about the module. If you want to test those installation instructions, you can run the commands listed in the README file to install the module on your system. At the moment your module does nothing but it is useful to know module-starter has generated everything you need for a working module including the code for it's installation.

You can find this code in the Makefile.PL file, which is a Perl script that defines how to build and install the module. It contains the necessary instructions for the make command to compile and install the module on your system. For now, we will not go into the details of the Makefile.PL file, but it is worth noting that it is an essential part of any Perl module distribution.

Next, let's take a look at the MANIFEST file, which lists all the files in the module. This file is useful for distribution and helps ensure that all necessary files are included when the module is packaged for release. You can package the distrubution for relase via the make dist command. The MANIFEST file should look something like this:

Changes
lib/Module/Test.pm
Makefile.PL
MANIFEST            This list of files
README
t/00-load.t
t/manifest.t
t/pod-coverage.t
t/pod.t

IF we were to add more files to the module, we would need to update the MANIFEST file to include them, you can do this by running the make manifest command, which will automatically update the MANIFEST file with the current files in the module directory.

Module Starter has also generated a t/ directory, which contains test files for the module. These tests are essential for ensuring that the module works correctly and meets the expected behavior. The tests are written in Perl and can be run using the make test or the prove command. We will cover testing in more detail in the next post.

For now, we will focus on the lib/Module/Test.pm file, which contains the module code and its POD documentation.

Let's open the lib/Module/Test.pm file and take a look at the POD documentation that is generated by Module::Starter. The file should look something like this:

package Module::Test;

use 5.006;
use strict;
use warnings;

=head1 NAME

Module::Test - The great new Module::Test!

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.01';


=head1 SYNOPSIS

Quick summary of what the module does.

Perhaps a little code snippet.

    use Module::Test;

    my $foo = Module::Test->new();
    ...

=head1 EXPORT

A list of functions that can be exported.  You can delete this section
if you don't export anything, such as for a purely object-oriented module.

=head1 SUBROUTINES/METHODS

=head2 function1

=cut

sub function1 {
}

=head2 function2

=cut

sub function2 {
}

=head1 AUTHOR

LNATION, C<< <email at lnation.org> >>

=head1 BUGS

Please report any bugs or feature requests to C<bug-module-test at rt.cpan.org>, or through
the web interface at L<https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Module-Test>.  I will be notified, and then you'll
automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Module::Test


You can also look for information at:

=over 2

=item * RT: CPAN's request tracker (report bugs here)

L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Module-Test>

=item * Search CPAN

L<https://metacpan.org/release/Module-Test>

=back


=head1 ACKNOWLEDGEMENTS


=head1 LICENSE AND COPYRIGHT

This software is Copyright (c) 2025 by LNATION.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=cut

1; # End of Module::Test

As you can see, the lib/Module/Test.pm file contains a package declaration 'Module::Test' which helps Perl identify the module. It also includes the necessary use statements to import required modules and enable strict and warnings pragmas for better code quality. It also includes a version declaration, which is important for version control and compatibility and finally code wise two empty functions function1 and function2, it is expected you overwrite these. The rest of the file is dedicated to POD documentation, which is structured using various POD elements we discussed earlier.

The POD documentation starts with the =head1 NAME section, which provides the name of the module and a brief description. The =head1 VERSION section specifies the version of the module. The =head1 SYNOPSIS section provides a quick summary of what the module does and includes a code snippet demonstrating how to use it. The =head1 EXPORT section lists any functions that can be exported from the module, although in this case, it is empty since we haven't defined any functions yet. The =head1 SUBROUTINES/METHODS section lists the functions defined in the module, along with their documentation. Each function is documented with a brief description and a code snippet if applicable. The =head1 AUTHOR, =head1 BUGS, =head1 SUPPORT, and =head1 LICENSE AND COPYRIGHT sections provide information about the author, how to report bugs, where to find support, and the license under which the module is distributed. The =cut directive marks the end of the POD section, indicating that the rest of the file is code. The 1; at the end of the file is a common Perl idiom that indicates the module has been loaded successfully. The # is an inline comment, I've not explained them before but you have seen and used them already, so you now know to add inline comments in Perl it is as simple as prepending '#' before your text.

Now that we have explored the generated POD documentation, we can see how easy it is to write and maintain documentation within the module code itself. This makes it easier for other developers to understand how to use the module and contributes to better code quality.

In summary, POD is a powerful tool for documenting Perl modules and scripts. It allows you to write documentation directly within your code, making it easier to maintain and understand. The Module::Starter tool has generated a basic module structure for us, including the necessary files and directories for a working module. We have explored the README file, the MANIFEST file, and the main module file with its POD documentation.

In the next post, we will cover how to write tests for our module and how to run them using the prove command. Testing is an essential part of software development, and it will help us ensure that our module works correctly and meets the expected behaviour.

If you have any questions or comments about this post, feel free to reach out.