With Perl if you store a file alongside your module with the same name but with a .pod extension instead of a .pm extension, perldoc will find it. If you're packing for CPAN make sure your MANIFEST includes it, though.

$ cat lib/Mymod.pm
package Mymod;

use strict;
use warnings;
use Exporter;
our @EXPORT = qw(greet);

sub greet {print "Hello\n"}

1;

.....


$ cat lib/Mymod.pod 
=pod

=head1 NAME

Mymod - Perl module to say hello.

=head1 SYNOPSIS

    use Mymod;
    greet();

=head1 DESCRIPTION

Example module.

=cut


.......

$ PERL5LIB='./lib' perldoc -T Mymod
NAME
    Mymod - Perl module to say hello.

SYNOPSIS
        use Mymod;
        greet();

DESCRIPTION
    Example module.
[download]

I can't seem to find where this feature is documented, but it's not hard to find it in use on CPAN.