|Keep It Simple, Stupid|
Deriving meaning from source code, some code is self documentingby submersible_toaster (Chaplain)
|on Dec 08, 2008 at 12:37 UTC||Need Help??|
Can useful documentation be derived from perl source, by source analysis alone? This would mean parsing perl, which is said to be hard.
Don't get me wrong. I like pod , my pod is forever improving - however when confronted with the horror of one particular brand of home grown, half baked XML class doc dangling beyond __END__ markers or lurking inside =pod/=cut , I cannot help but ponder documentation, self documentation and (save me) auto documentation.
Some months ago , in the throes of hacking on a large OO-ish perl codebase , thwarted by lack of pod and an overabundance of outdated XML fluff - I returned to the source only to find it a descent through layers and layers of subclasses of classes inheriting frameworks of further classes and subclasses.
First consider that My::Class::Foo's method 'load' is failing and the problem appears to be with $path. Seeing that variable is returned by the object method 'canonpath' , we can go look for that method.
Seems that canonpath must be inherited since it is not defined in My::Class::Foo , which leads on a search discovering ...
Nuts! , no joy with My::Class either , the documentation is no help - pod missing presumed dead - XML fluff only tells me what I can plainly see which is My::Class::Foo inherits from My::Class which inherits from More::Generic , with heavy heart let us open More::Generic in anticipation of an end to this pursuit.
Closer. Since the familiar File::Spec is the parent class here, we can finally resort to the mystical practice of documentation perusal, perldoc File::Spec
This is a rather contrived example (and my apologies to File::Spec) . My frustration at being faced with this combination of deep inheritance and missing documentation lead to a short brutal script that attempted to find and chase instances of 'use base' and outputting short pod sections like
After some experimentation I believe that when expressed as PPI elements , the use base qw(Classname); idiom can be matched and used to derive meaningful documentation about perl source. In fact this idiom is a special case of importing behaviour - like use POSIX qw( strftime );. To PPI , these are include statement elements with trailing data, albeit often very different trailing data with specific meaning with respect to the package being imported.
In processing perl source, allow a plugin to capture the include of a chosen module and any import arguments. Add new plugins for more meaningful output
I'm compelled to try writing a parser which turns perl source into a document describing the nature of that source code, dependencies, ancestors, imported and exported symbols. This document's interface would be used by a formatter / processor to produce or embelish existing documentation. So far I have a terrible document model, a lame parser and a missing original script.Their namespace is Macropod , as in Big and Foot.
First meditation in ages. be kind
I can't believe it's not psellchecked