in reply to Perldocs and peer reviews
The problem with that is that it's possible for the docs to be clear, seem complete, and describe friendly syntax... and be wrong. The docs for Math::Matrix, for example, fail to describe a very useful feature -- that the objects have a number of overloaded operators. Somebody just reading the docs and not the code wouldn't be able to tell. (Reminds me; I never got around to writing a bug-report on that.)
It's possible for modules to even have example code in their docs that doesn't run -- something undetectable without actually installing the module. This is what Pod::Tests and other similar modules are for, but not everybody (myself included) uses them.
Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).