I agree, but with some clarifications.

When speaking of documentation, I mean things that document the particular module, philosophy, code snippet, or whatever the documentation is related to. If someone starts documenting how pack() works in the middle of the code or API then he's just lost track of what he's doing.

However, there seem to be couple of misunderstandings here between fellow monks. Some speak of documentation, some speak of commentation, and some speak of commentation as documentation. Naturally, disagreements will arise.

I usually wouldn't refer to comments as documentation. If someone says "look in the documentation" I certainly don't look for comments. I say that there can be too many comments, but too much documentation has never hurt me--as long as it has a sensible structure. If you end up with a long documentation with lots of examples and explanations in it you'd perhaps should start thinking about writing a separate tutorial or extract the examples to an own section. Has anyone ever complained about too many examples?

For modules this means that you first document the most important things so people quickly can use your module. But towards the end of the documentation you very well can put a more detailed explanation and give examples to illustrate special features, nifty uses, or gotchas. If it's a "funky" module, i.e. it does something technically advanced with Perl itself (constant.pm to take a well-known module) it can be interesting with a little explanation or forward to documents explaining how the module achieves what it does so the reader gets a chance to learn and understand rather than being a simple user. This certainly can help the module author with finding bugs or even receiving patches. It also feeds for further development and other related and interesting ideas. So no, I wouldn't say that there can be too much documentation. (Remember that I don't count a pack() tutorial in the middle of code as documentation.)

Just my thoughts,
ihb