You write a module, or a whole suite of modules, and (hopefully) nicely document all the methods in the classes next to the code. Great!
Only now the problem is that the module suite is using some best practices, and builds re-usable base classes on top of re-usable base classes, until the actual user-usable classes are just icing-on-the-cake layers on top.
Now your users have to figure out which methods on their resulting objects come from which of your base-base classes, and dive into various different pieces of documentation to piece together the methods they can call.
No longer!
Having been annoyed enough by this sort of POD wrangling already, theorbtwo came up with Pod::Inherit to help the module writers improve their documentation. Run it with the name of a class or the lib directory for your distribution, every class is investigated to determine which methods it contains, the inheritance tree is then searched to determine which base class actually defines that method. After the collection is complete, the POD from the original file is written to a new file with the extension ".pod" and adds a "INHERITED METHODS" section at the bottom (after all other sections, before any section named LICENSE, AUTHORS and so on.
The INHERITED METHODS section consists of a list of classes the current class inherits from, with a link to that class. It then lists the names of the inherited methods. This will also include methods that are outside the current distribution tree, for example if the module inherits from Class::Accessor::Grouped, then "mk_group_accessors" will be listed.
So, having waffled a lot, here's what the output looks like when we run it over DBIx::Class:
As an extra, I got annoyed enough at Apache::Pod for always linking to search.cpan.org when displaying links in my local documentation, that we came up with a way to have it figure out whether the link was in the local tree of files, and link there, or whether it was a true external link.
Unfortunately in singleton mode (i.e. just parsing a single file, as it is when installed as an Apache PerlHandler), it can only guess by recursing up the file tree until it finds a directory that doesn't look like a class name. Unpretty, but works if you make the dirs all lower-case (yes, pragmas don't count).
In batch mode however, it does have a good clue what its working on, so there it knows exactly what it can link, and what not.
So having fixed that, we can run it over the DBIx::Class pod-inherited docs, and get sane linking too!
DBIx::Class pod, inherited and linked sanely
How's that for annoyed programmers?
@public,perl,pod,dbix-class,dbic
Last modified: 2009-03-30T20:49:44