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

Answer 2

Don't duplicate documentation, it will go out of sync, just provide links to the original documentation and document the differences.

Answer 3

You should think about renaming your module. I think Foo::Cached would be common practice. I usually indicate inheritance only in the relevant sections e.g.:

=head1 METHODS

L<Foo::Cached> inherits all methods from L<Foo> and implements the following methods by itself:

...

If you still want to see all the inherited methods you could use Pod::Inherit to create a temporary podfile which also includes the POD from the parent modules (or if you are building something bigger, you could try Pod::Weaver.