|Problems? Is your data what you think it is?|
Re^2: Deriving meaning from source code, some code is self documentingby submersible_toaster (Chaplain)
|on Dec 11, 2008 at 01:55 UTC||Need Help??|
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.
I can't believe it's not psellchecked