On Sun, Sep 23, 2001 at 10:05:57PM -0400, Dan Sugalski wrote:
> I see there's a lot of embedded documentation going into the core, and
> that's a good thing. That brings up a question, though--what exactly should
> we document, and where should it be seen?
>
> For an example, the opcode functions should *never* be used outside the
> interpreter core itself, but documenting them's still a good thing.
>
> Maybe we need a way to tag the type of documentation for each function--the
> module it belongs to and how exposed it should be, or something.
Assuming we're using POD, the simplest thing to do is thus:
=begin _private
Private docs you don't want displayed by perldoc, but want someone reading
the source to see.
=end _private
POD has the advantage over plain comments of imposing an implied
structure on the docs. It also means a future "--private" flag can be
added to perldoc to display them.
Works pretty well so far for CPAN modules.
--
Michael G. Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One
List context isn't dangerous. Misquoting Gibson is dangerous.
-- Ziggy
