I write good docs because I have a bad memory. The docs are there to
remind me what I was working on. This is all fine and dandy except
when it comes to the private bits of a program. Private methods,
internal functions, magic internal variables, etc... Now, I could
just write comments to document all that, but then I can't use perldoc
to see the complete docs for the code, and besides that's just yicky.
I was just poking around in the File::Temp docs and noticed this:
=begin __INTERNALS
Some notes about the guts of the module.
=end __INTERNALS
Hey hey! Why not?
=begin _private
=item B<_something_internal>
my $thing = $obj->_something_internal;
Blah blah blah
=cut
sub _something_internal {
...code...
}
=pod
=end _private
And a perldoc --private flag (or -p or whatever) to display it along
with the rest of the docs!
This will require some modification to pod2man and pod2text, but
nothing difficult.
There might be some concern about exposing internal interface to the
user, but this is in keeping with Perl's Good Neighbor policy. If a
user reads and relies on the internal interface, its their own damned
fault. Anyway, they could just read the source.
Thoughts?
--
Michael G Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One
