Why would someone want to document private methods?

Because in Perl if you just use the leading underscore convention and the -> calling style you can have problems with subclasses using the same method name.

This does not strike me as a good reason.

Experience strongly suggests that if you use descriptive method names, collisions are rather rare, documentation is never accurate, and it is as easy to search code for private methods as it is documentation. (Besides, I'm always going to search the code in the end because I don't trust the documentation.)

Furthermore no amount of documentation can protect you if the base module's implementation changes and it now needs a new private method that might intersect what some subclass is using.

This is part of what I was referring to at Re^2: Private Methods Meditation. And there is no perfect solution to it. However after you use descriptive method names and have decent test suites, the problem virtually goes away. If you furthermore have somewhat decent designs, the issue becomes rare to the point of being an endangered species.

I'll continue my practice of not documenting private methods in POD. They are in source code, and possibly in regular comments when needed. That is good enough.

Furthermore no amount of documentation can protect you if the base module's implementation changes and it now needs a new private method that might intersect what some subclass is using.

You hit the head of the nail here. That's why you shouldn't use methods calls on "private methods" (update: private methods in the java sense, not just "non-public" methods)--to avoid that intersection with any subclass. Though, you alrady have a large code base that uses $self->_private you can document these methods (just that they exists and are called as methods with suffice) instead of patching every methods call. (And then you of course should stop using method invocation on private methods.)

ihb

Read argumentation in its context!