in reply to Inline POD vs. EOF POD
I've mainly two reasons for that. A theoretical one, and a practical one.
Let's start with a practical one. Ever tried figuring out what a module is exactly doing? Ever tried that with modules that use inline POD? It's like eating soup with loads of hair in it - you can't quickly see what is code and what is POD, especially if the POD uses code blocks! It becomes harder to find the functions.
But the theoretical one is more serious. POD is for writing *user* documentation. That's why pod2man is run. And user documentation describes how you use a program, or a function. Not how it's implemented, unless that's relevant to the usuage. Regardless whether it's a module or a standalone function. Look at your systems manual pages, be them from section 1, 2 or 3. They talk about usuage, not implementation. Furthermore, the best way of describing how to use a command or function is very seldom done in the same order as your code is. Do you think the "ls" command has to code for dealing with the various options in alphabetical order? Or do you think the options shouldn't be described in alphabetical order, but in the order the programmer just happens to group them?
I use block comments to explain the implementation, and POD to explain the usuage. And IMO, if you use only POD, you either have lousy manual pages, or your code is very lousy documented.
-- Abigail