Should I copy perldoc for inherited methods to the subclass's documentation?

Question

I've written a class foo.pm that collects some data from a web service. Inside foo.pm I have added perldoc to describe the functionality as well as a short guide on the usage. There's a reference for all its methods.

I've also written a subclass cachedFoo.pm, that uses foo.pm as a base class, wraps its own constructor around foo's new method and upgrades foo with a database connection to cache the results. I've already added perldoc to cachedFoo.pm for the additional stuff.

Now I only want my colleagues to use cachedFoo.pm. Should I copy the perldoc for all the inherited methods from foo.pm to cachedFoo.pm or should I just say "look at the base class's docs for the accessors"? Or is there maybe another way?

Answer 1

It suffices to conspiciously point to other classes once near the start of the interface description, see best practices documentation example below. Your pod coverage test then should employ Pod::Coverage::CountParents to take inheritance into account.

package cachedFoo;
⋮
=head1 INTERFACE

=head2 Composition

    cachedFoo
        ISA foo
        DOES somerole

All methods and attributes not mentioned here are
inherited from L<foo> or mixed in from L<somerole>.

=head2 Methods

=head3 C<cache_database_thing>

Blah blah blah, Mr. Freeman

Naming each composed method explicitly does not scale. I can't recommend this:

=head3 C<quux>

See L<foo/quux>.