You need to document your module, but don’t know what format to use.
Embed your documentation in the your module file using pod format.
Pod stands for plain old documentation. It’s documentation embedded in your program using a very simple markup format. Programmers are notorious for writing the code first and the documentation never, so pod was designed to make writing documentation so easy that anyone can and will do so. Sometimes this even works.
When Perl is parsing your source code, a line starting with an equal
sign (where a new statement is expected) says to ignore all text
until it finds a line beginning with
which it will start parsing code again. This lets you mix code and
documentation throughout your Perl program or module file. Since
it’s mostly plain text, type in your documentation as literal
text, or nearly so. The translators try to be clever and make
output-specific decisions so the programmer doesn’t have to
specifically format variable names, function calls, etc.
Along with Perl are shipped several translators that filter generic pod format into specific output styles. These include pod2man to change your pods into troff for use with the man program or for phototypesetting and printing; pod2html for creating web pages (which works even on non-Unix systems); and pod2text for plain ASCII. Other translators, like pod2ipf, pod2fm, pod2texi, pod2latex, and pod2ps, may also be available or can be ...