Должен ли я скопировать perldoc для унаследованных методов в документацию подкласса?

Question

Я написал класс foo.pm который собирает некоторые данные из веб-службы. внутри foo.pm Я добавил perldoc, чтобы описать функциональность, а также краткое руководство по использованию. Там есть ссылка на все его методы.

Я также написал подкласс cachedFoo.pm, который использует foo.pm как базовый класс, оборачивает свой собственный конструктор foo"s new метод и обновления foo с подключением к базе данных для кэширования результатов. Я уже добавил Perldoc в cachedFoo.pm для дополнительных вещей.

Теперь я хочу, чтобы мои коллеги использовали cachedFoo.pm, Должен ли я скопировать perldoc для всех унаследованных методов из foo.pm в cachedFoo.pm или я должен просто сказать "посмотрите на документы базового класса для аксессоров"? Или есть другой способ?

Answer 1

Достаточно явно указать на другие классы, когда они находятся в начале описания интерфейса, см. Пример документации по передовому опыту ниже. Тогда ваш тест покрытия pod должен использовать Pod:: Coverage:: CountParents, чтобы принять во внимание наследование.

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

Наименование каждого составного метода явно не масштабируется. Я не могу рекомендовать это:

=head3 C<quux>

See L<foo/quux>.

Answer 2

Не дублируйте документацию, она будет синхронизирована, просто предоставьте ссылки на оригинальную документацию и запишите различия.

Answer 3

Вы должны подумать о переименовании вашего модуля. Я думаю, что Foo::Cached будет обычной практикой. Я обычно указываю наследование только в соответствующих разделах, например:

=head1 METHODS

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

...

Если вы все еще хотите увидеть все унаследованные методы, вы можете использовать Pod::Inherit для создания временного подфайла, который также включает POD из родительских модулей (или, если вы создаете что-то большее, вы можете попробовать Pod:: Weaver.