On Thu, 15 Aug 2002, Stephen Adkins wrote: > On another note: > I seem to recall that Dave Rolsky did something with a script called > pod_merge.pl in Alzabo to merge the POD doc for methods inherited > from a parent class into its child classes.
Indeed I did. > Question: What are people's opinions? Is the best way to handle > the documentation of inherited methods to: > > 1. provide a link (or "see also") in the subclass to the parent > class documentation, or > 2. duplicate the documentation for the inherited method from the > parent class doc into the child class doc It depends. Alzabo is built so that there is a base class, Alzabo::Table (for example), which has two child classes, Alzabo::Create::Table (used to set table 'object' attributes, like name, columns, etc.) and Alzabo::Runtime::Table (used to retrieve data from the table in the form of Alzabo::Runtime::Row objects). The key point here is that there is no actual use for the Alzabo::Table classe _by itself_. In fact, it doesn't even have a constructor. But it _does_ provide actual working methods for returning the table object's attributes like name, columns, etc. These methods are useful for both of the child subclasses, but it'd be annoying to have to constantly jump between the parent and child classes, particular when the parent contains the "get" methods and the child contains the "set" methods. So I decided to just merge in the POD docs. If, OTOH, the parent was useful _by itself_, and the child was an _extenstion_ of the parent, in which case we'd expect the child to only have a few unique methods, then merging in the POD docs may not be worthwhile. -dave /*================== www.urth.org we await the New Sun ==================*/
