# from Ken Williams on Thursday 19 April 2007 05:04 am:
>On Apr 14, 2007, at 4:17 PM, Eric Wilhelm wrote:
>> 2. If documentation is found in a subclass and superclass, should
>> we be
>> concatenating them together? It really seems like we should just
>> stop when we find some doc.
>
>I guess the answer depends on whether the author is writing their POD
> primarily for someone to read in the pod doc, or for the 'help'
> action. The main difficulty probably happens when someone overrides
> a method to add a small piece of functionality to it, because then
> their docs will probably just say "does the 'foo' action and also
> does 'bar'". And the user still won't know what 'foo' does.
True. We should either stop by default and have some directive that
says to keep descending or vice-versa.
Considering how it will look in a pod viewer, something like this would
be best:
=head2 foo
Makes foo depend on bar.
See L<Module::Build/foo>.
So, we would then want to continue descending @ISA if
m/L<[^>]+Module::Build\/$action>/ or so. Possibly even s/// it?
Alternatively, we use an actual directive, but that would mean you also
need a link for the podviewer case.
=for Module::Build podparents
The m/L<.../ case is a bit more dwim, the directive is explicit, but
can't be dual-purpose. I'm leaning toward the L<> match, probably with
s/^See L<[^>]+Module::Build\/$action>\.?$/$parent_pod/ action to allow
dwim without syitf (Shoot Yourself In The Foot.)
--Eric
--
Moving pianos is dangerous.
Moving pianos are dangerous.
Buffalo buffalo buffalo buffalo buffalo buffalo buffalo.
---------------------------------------------------
http://scratchcomputing.com
---------------------------------------------------
