On Thu, Feb 09, 2012 at 11:33:21AM +1000, Florent Angly wrote:
> The POD content of a module can be written into its Perl file or into a
> separate .pod file. There are quite a few examples of modules around
> that use one method or the other. However, is it allowed to put part of
> a POD documentation into the .pod file and the other part in
> corresponding Perl files? In other words, if a .pod file exists for a
> module, should I bother looking for POD into the corresponding Perl
> file? Are there examples of Perl modules using POD in a .pod and .pm
> file or is it simply a theoretical case?
I doubt you'll ever see a distribution which has POD in both Foo/Bar.pm
and Foo/Bar.pod, because the perldoc tool will only see one or the other
when a user types 'perldoc Foo::Bar'.
Having POD in both .pm and .pod files in a distribution is fairly common,
but in that case the .pm file's POD will typically tell you how to use the
module, and the .pod file's POD will normally be either documentation of
internals, or explain how to sub-class or extend - and, of course,
they'll have different names:
perldoc Foo::Bar # tell the user how to use Foo::Bar, comes from .pm file
perldoc Foo::Bar::Extending # how to extend Foo::Bar, comes from .pod file
--
David Cantrell | Hero of the Information Age
You are so cynical. And by "cynical", of course, I mean "correct".
-- Kurt Starsinic
