Re^2: The sourcecode *is* the documentation, isn't it?

[deprecated]

I cannot comprehend how anyone could say that any form of documentation (save that which is incorrect or absent) is "... rude ..." Even private functions should be documented. An example from an API I wrote a while ago (for a largeish company, but not on CPAN, sorry) included documentation for all the private functions because otherwise it was unclear what they did. In this example, the API served to perform exotic math on matrices. One couldn't use simple operators because the operators didn't operate in the exotic way the API required. So private, "behind-the-scenes" functions were made to perform these operations (I suppose we could use some of the newer perl functions with respect to overloading or defining our own operators, but this was a while ago, and those new techniques would still have to be documented).

So let's say there were functions like _alex_weird_add() and _alex_weird_multiply(). Definitely private functions because they performed tasks that weren't "add" or "multiply." I didn't want the user using them, I didn't want them exposed to the rest of the API, but I needed to make sure that somebody down the line (there is always churn in software shops) would be able to read my POD (and in this case my Params::Validate clauses too) and be enlightened.

To suggest that not having the documentation somehow makes the reader of the code ... less in the dark just seems entirely to miss the point of documentation.