There is a certain level of 'boilerplate' information (let's not call it documentation) that other more strictly parsable languages tend to provide as part of code documentation. The approach described is without a doubt driven by analyze bad code , for certain values of bad.

In general a list of methods by itself is not documentation, neither is an inheritance tree

In general - would you expect an author to document , in POD linked references to parent classes / dependencies in a helpful =head1 INHERITS or =head1 DEPENDS ON section? This is the sort of boilerplate that is a) manual and tedious , b) comes for free with many other languages, c) prone to outdated-ness(see a)

Generate documentation - no. Enhance existing documentation - yes. Soften the blow in the absence of ANY documentation - maybe. Provide hints to author/maintainer about the nature of a piece of code versus the nature of the associated documentation - possibly.

The zero day script simply tacked it's conclusions (as pod) onto whatever pod already existed before passing that to a final formatter, in this case HTML. I wouldn't suggest baking it's output back into the original code anymore than I would suggest perlcritic users insert comments in their code for every critic message.

Perhaps consider Macropod to be a step towards a Pod::Critic which in addition to nagging about common pod formatting mistakes, would suggest that you only appear to have pod sections for functions 'foo' and 'bar' , but are exporting '&zebra' which has no associated documentation.