good examples of POD documentation

perl5ever has asked for the wisdom of the Perl Monks concerning the following question:

Replies are listed 'Best First'.
Re: good examples of POD documentation by eff_i_g (Curate) on Mar 05, 2009 at 16:40 UTC
Not exactly what you've requested, but helpful, perhaps: POD conventions	[reply]
Re: good examples of POD documentation by Bloodnok (Vicar) on Mar 05, 2009 at 16:44 UTC
I personally prefer and extend the template generated by h2xs but I would suggest that that opinion might be tainted ... thro' willing over-exposure :-D Your decision might also be affected by your development environment e.g. Eclipse/E-P-I-C doesn't appear to like the standardised h2xs approach. It may also be that your employer/client might have substantial view of/influence on your choice. Afterthought: looking at some of the Test::Pod modules e.g. Test::Pod::Coverage, might provide some helpful information... A user level that continues to overstate my experience :-))	[reply]
Re: good examples of POD documentation by ELISHEVA (Prior) on Mar 06, 2009 at 12:45 UTC
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: NAME section - name of function in bold followed by a one line description. 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 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 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". AUTHOR - section listing everyone who wrote or helped with the module. 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	[reply] [d/l] [select]
Re^2: good examples of POD documentation by JavaFan (Canon) on Mar 06, 2009 at 14:19 UTC
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. I'm one of the people who puts the POD after the __END__. For the reasons you mention and for an additional reason: I often don't document the code in the same as they appear in the code. In the code, you may want to keep methods accessing the same data close to each other, but for documentation you may have other considerations. I typically use methods I expect to be used often early in the documentation, while lesser used method are documented further down. Sometimes I prefer the documentation to describe the methods sorted lexigraphical. And if the description of method A is build on the description of method B, I like to have in the documentation A right above B. Moving the documentation "out of the way" gives me the freedom of moving documentation (and code) around without changing the order.	[reply]
Re: good examples of POD documentation by locked_user sundialsvc4 (Abbot) on Mar 05, 2009 at 16:59 UTC
Probably the best source of advice is ... existing modules on CPAN. And, follow your own instincts: what represents “great documentatation” to you?
Re^2: good examples of POD documentation by JavaFan (Canon) on Mar 05, 2009 at 18:24 UTC
Probably the best source of advice is ... existing modules on CPAN. That's a silly advice. Anyone can upload any crap on CPAN, and many people do. There are modules with good POD on CPAN, but there are also modules with shitty or hardly any POD on CPAN. The existence of a module on CPAN does not imply anything about its quality (code nor documentation wise). Just pointing to CPAN isn't very helpful in this case.	[reply]
Re: good examples of POD documentation by kyle (Abbot) on Mar 05, 2009 at 16:34 UTC
Do you want to learn the nuts and bolts of POD (perlpod), or are you looking for examples of good documentation that happen to be written using POD?	[reply]
Re: good examples of POD documentation by jplindstrom (Monsignor) on Mar 06, 2009 at 14:24 UTC
Who is the audience for the documentation? Is it a programmer who needs to learn how to use the module and call it from their own programs? Or is it a programmer (you / your team mates) who needs to know how it works so they can work with and extend the code? These two audiences have two quite different needs. /J	[reply]