>
good examples in the synopsis
The SYNOPSIS is just that, a "quick start" or "tldr;" on how to get to something more interesting. It is not a treatise expounding on the inards of your functions.
Similarly, POD detailing the the methods is best written as "this is the intent of this function". It is not a full break down of the implementation and what constitutes it running successfully. This is what unit tests are for - and unit tests can also serve as excellent documentation themselves. If your goal is really to expound on the gritty details of a function or method, this is probly best done around the function it self. The code should be enough to describe what is happening. And if it isn't then a few well placed internal comments (behind the #) would work well.
Lastly, a good rule of thumb is that updating the code of a function should require documentation updates only in extreme cases (e.g., when IN/OUT changes, exceptions are added or removed, etc).