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

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?

Solution

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>.