Front page | perl.perl6.internals |
Postings from September 2001
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 <schwern@pobox.com> http://www.pobox.com/~schwern/ Perl6 Quality Assurance <perl-qa@perl.org> Kwalitee Is Job One List context isn't dangerous. Misquoting Gibson is dangerous. -- ZiggyThread Previous