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?

score 3 · Answer 1 · answered Jul 18 '12 at 13:27

3

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

answered Jul 18 '12 at 13:27

kixx

3,245
22
19

score 3 · Accepted Answer · answered Jul 18 '12 at 15:17

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

I think I'll go with this example. Thank you. – simbabque Jul 19 '12 at 20:32 — simbabque, Jul 19 '12 at 20:32

score 2 · Answer 3 · answered Jul 18 '12 at 15:39

2

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.

answered Jul 18 '12 at 15:39

Sebastian Stumpf

2,761
1
26
34

Thanks for the tip on the naming convention. I thought about that but wasn't sure. – simbabque Jul 18 '12 at 17:24
About that naming convention: Would you still do that if there only is the one subclass? – simbabque Jul 19 '12 at 20:27
Yes, I would. **Especially** if other programmers will use that code, too. Unnested module names will lead only to confusion, especially in larger projects. Choosing nested names could also prevent compatibility issues. Some filesystems limit the length of their filenames to `8.3` characters, so `cachedFoo` could be already too long... – Sebastian Stumpf Jul 19 '12 at 23:07

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

3 Answers3