Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

jplindstrom (594)

jplindstrom
  (email not shown publicly)

Journal of jplindstrom (594)

Friday April 18, 2003
04:55 PM

Public Health Warning: OO Documentation is Itchy

[ #11730 ]

Every good work of software starts by scratching a developer's personal itch
--ESR

Browsing through the modules@perl.org archive I found Mark Overmeer's OODoc application.

It tries to solve a common problem with documenting classes and inheritance hierarchies; classes inherit from each other, but the documentation local to each class isn't necessarily presented in the same manner. The interface of a subclass is fragmented without the parent class taken into account.

In general, method overriding and late binding can make OO code difficult to understand, so decent docs/class browsers are often vital aids when trying to form an understanding of OO systems.

From university, I remember the language Eiffel dealing with this by providing a flattened view of a class and it's ancestors, both the docs and the actual code. Very useful.

So with that in mind I wrote something similar to merge POD sections from inherited classes a couple of years ago. It never felt stable or mature enough though, so I never released it. But other people seem to experience the same problem with documenting class hierarchies, scratching the itch as it becomes evident.

OODoc is now on CPAN.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Alzabo has one set of base classes from which two distinct sets of children inherit. I wrote my own little pod merging tool to merge docs from the base classes into the children. It's a nasty hack, but useful for end users, I think.