Asking for good examples of POD is a little like asking for good examples of a web page. What's good depends on the complexity of your module, your development needs, your production environment, and even your personal style. There is a lot of variety in both visible content and internal placement of the POD that creates the content. I'll highlight a few points here, but my recommendation is that you study some CPAN modules and ask yourself "What works (communicates well) and why?" Then develop a style of your own.

There is a basic skeleton that many of the CPAN modules seem to follow. This consists of the following sections:

1. NAME section - name of function in bold followed by a one line description.
2. various descriptive sections - often this is divided into two sections. The first is a SYNOPSIS section that gives a quick thumbnail sketch of the module's capabilities, usually via sample code or a list of function/methods. The second is a much longer section titled DESCRIPTION. This covers all the points that may not be obvious from the synopsis. However, the number and organization of the description sections can vary a lot depending on the complexity of the module
3. CAVEATS (sometimes titled "BUGS AND CAVEATS", "NOTES AND CAVEATS", "NOTES" or "BUGS") - one or more sections listing known bugs, unrealized implementation goals, and general restrictions on use contexts - for example: operating system limitations or whether or not the module plays well with Apache and mod_perl
4. SEE ALSO - section listing related modules. Modules can be related because they do the same thing a different way, provide helpful background information or because they are a useful complement to module at hand. Sometimes you will also see a brief description explaining why they should be "seen also".
5. AUTHOR - section listing everyone who wrote or helped with the module.
6. COPYRIGHT - section listing who holds the copy rights and licensing agreements.

To sort out what information belongs in your description sections is probably the hardest part of writing good POD. A lot depends on the complexity of your module:

• Do you have a purely functional interface? An OO interface? Both?
• Do your functions or methods have a lot of similar parameters?
• Do they fall naturally into groups that should be discussed together? Do they have a natural order of application - i.e. first use method A, then B, then C?
• Are the parameters simple scalars, arrays, and hash references? Or are there parameters that need significant explanation - for example, a subroutine that takes a special set of parameters; a hash with a list of keys with special meanings; a string that is a mini-language in its own right; or a string, hash, or array that must be created
• Is the reason for each function obvious or do you need to provide background information and context so that users understand why each function exists and when it would be appropriate to use?

If the parameters are simple and the role of each function is pretty obvious from its name, you may be able to get away with documentation that consists of a brief SYNOPSIS section followed by a DESCRIPTION section briefly describing each function and its parameters one by one.

If there are a lot of similarly defined parameters, it is often a good idea to have the synopsis section use consistent variable names for each parameter. Then include a subsection of DESCRIPTION explaining what values parameters $x, $y, $mumblefoo can take. This can save a lot of time for your module user: without users have to scan back and forth between your individual function descriptions to figure out if $x in makeFred($x) has the same meaning as $x in in makeBarney($x). Not fun.

For more complex modules, its hard to come up with rules of thumb, so I refer you back to the original advice: study a variety of CPAN modules and ask yourself - what does and does not get its point across and make the module easier to use?

Once one has figured out what to document, the next question is where to document. There are several styles and I don't know that one is right - they suit different programming styles, maintenence and production needs:

• close to the code - some people like to keep function and method descriptions next to the code they document. If you are going to use this approach, you'll have to mentally divide your documentation into three groups: stuff before the functions, the functions and stuff after. The POD for stuff before (e.g. NAME, SYNOPSIS would go at the top of your source file. The stuff after (e.g. CAVEATS, AUTHOR, etc) goes at the bottom.
• in the file but out of the way - some people feel that keeping documentation, especially lengthy documentation close to each function makes it difficult for them to get a good birds eye view of a module. This is particularly true if your team has a lot of people that are very fluent in reading code. To get POD out of the way, some people prefer to place all of the POD at the top or the bottom
• separate file - you can also place your pod in a file that has the same name as your module but ends in .pod rather than .pm. This is a good approach if your module is complex and requires lengthy documentation. Its a bit of waste of parser power and CPU time to chomp through lengthy documentation just to get at a few lines of code. The down side of this approach is that it takes more work to keep the interface described in the documentation in sync with the code.

One final issue relating to POD is the role of "hidden POD". POD can be used for many things including in-line test cases, private developer notes, and cook book examples. The normal document generator will quietly ignore =foobar if it doesn't know what foobar is supposed to mean. There are numerous modules on CPAN that take advantage of this feature to embed all sorts of maintenence related information in source code files. For example, see Test::Inline for inline test cases and Test::Cookbook for cookbook examples that double as executable code. (Note: I don't use either of these modules - so I can't vouch for their safety)

Best, beth

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.