I use normal POD for subroutines, but use the "=begin" pod command designate a different translator to process those sections. I call my programmer documentation sections "programmers" docs, and I created a little "translator program" that just identifies the programmerdocs sections, strips them out, and passes them on to the standard pod translators.

That way, 'perldoc' gives me the user documentation, and my 'programmerdocs' script gives me the programmer documentation. This also allows a tester who is unfamiliar with the program to black box test each function without knowing the internals of the code: if the code doesn't match it's documentation, one of them needs fixing. This would be more useful if we had a testing department, but hopefully it's still of use to document.

I consistantly use the same template for documenting each function: first the name and arguments, then a one line description of the purpose of the function, then a detailed description, then the return values section, the global variables used (indicating read/write status), any preconditions (such as open filehandles, etc.), any postconditions (program termination conditions, warnings emitted, filesystem modifications, etc).

By documenting the pre and post conditions carefully, I usually end up thinking about the error handling of my functions (ie. "the routine emits a warning: but should it throw an exception instead?" or "The program dies if we hit an error condtion. Can/should it recover from this state instead?"). Thinking about formally documenting my decisions makes me think harder about the justifications I have for making each of those choices.

That's what works for me. I don't claim it should work for anyone else, though. :-)
--
Ytrew