Micheal,
On Jul 11, 2004, at 2:09 PM, Michael G Schwern wrote:
On Sun, Jul 11, 2004 at 12:26:44PM -0400, stevan little wrote:As for POD, in most cases, I agree with you, but to say you should have
100% POD coverage brings up several other questions, such as; Should I
document private methods?
IMPO yes, but Pod::Coverage (and thus Devel::Cover) will skip any method
starting with _ as well as the magic functions (import, DESTROY, AUTOLOAD,
etc...). So just name your private functions _foo and you're fine.
I did not know this, which will teach me to read the documentation more :)
I document private code like this:
=begin private
put your normal POD here
=end private
perldoc won't show the POD but someone reading through the code (and thus
needing to know about private functions) will see it. And POD is very
readable in its raw form. I use POD instead of comments to avoid having
a split documentation standard.
This too is good to know. Personally, I dont like to embedded POD in perl myself, and I also find that my comments tend to be for a different audience than my POD is for, so I don't see them as one in the same.
What about modules which are meant to be configured in the "use" statement, and have little or no subroutines which are intended for usage outside of the module (which I guess is sort of like private methods, but not)?
They're all private. Name them with _foo().
This is a more complex issue than this I think. They are private, but not in the same way that methods are private, and thus, I am uncomfortable with using that naming convention throughout. I actually view these types of modules as having a different kind of "interface" than your regular everyday module (an "import" or "use" interface for lack of a better term). It would be nice (but likely impossible to deal with the infinite variations of style) to be able to check if that interface is documented.
What about tied modules? It usually would not make sense to document the
tie hook routines.
I've just sent a patch to Richard to skip /^[A-Z]$/ by default. This nails
all the magic methods I can think of.
I think that reg-ex is too loose (and incorrect, but I know you really meant /^[A-Z]+$/). I would rather see it check for all the documented magic methods rather than a catch all for UPPERCASE names. Even though i know I am not "supposed to" I don't like the idea of not being able use UPPERCASE names if I want (and not have them mess up my POD::Coverage stats).
Although even this brings up the fact that if I did want to include documentation on those methods, its POD coverage would not get tested if POD::Coverage skipped them.
Which just bring me back the idea that maybe 100% POD coverage is not always a realistic goal.
I just had an idea. Per module private/trustme lists for Pod::Coverage.
=for Pod::Coverage trustme you_cant_find_my_docs()
=for Pod::Coverage private im_really_private()
Interesting idea, but personally I am always wary of anything that allows you to skip a coverage test manually. To me it is just a way to subvert the coverage tool, even if it is for the best intentions.
But then again, I use coverage tools for fun and not because I have to, so my views on this may be too idealistic.
Steve
