in reply to Re: Documentation: POD vs Comments
in thread Documentation: POD vs Comments
Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.
That's quite subjective. If *I* were the maintainer, you wouldn't score any brownie points.
But, as you said, POD isn't there for the maintainer - it's there for the user. POD doesn't have any way of modifying the order in which it appears in the source file. While there are some cases where you may present the documentation in the same order as the corresponding code appears in the source file, IMO, more often than not, that's not in the benefit of the user. My POD often contains sections that aren't directly related to any specific code (usually, only parts of the DESCRIPTION describe code), and those that do, I usually want to present them to the user in a different order. I may want to describe often used or general functions/methods before less often used, or specialist functions/methods. And sometimes I want to describe my methods in alphabetical order.
Interleaving POD with code means that the flow of your manual page depends on how the code was written. This is a case of "implementation shining through". Which I think is a thing that should be avoided.