I was curious as to what percentage of Perl'ers use POD for documenting their code. I was curious because I looked at the Template-Toolkit source and while there is POD after the __END__ there is also documentation in the code using normal # type comments. That seems redundant to me but is that the norm?
Also, is there a good "this is how you use POD" with examples (besides perlpod) somewhere?
Two different purposes
LTjake on 2008-01-22T01:56:26
pod and "#" comments serve two distinct purposes.
pod is for API documentation, usage examples, links (see also, websites, etc).
regular "#" comments are there to let the programmer know what is going on in a particular part of the code (see this perlbuzz post for examples:
http://perlbuzz.com/mechanix/2007/12/how-to-document-your-code.html)
HTH.
Re:Two different purposes
Aristotle on 2008-01-22T02:17:09
What he said.
In short, POD is for the guy who uses the code, whereas comments are for the guy who maintains it.
Re:Two different purposes
sigzero on 2008-01-22T02:37:24
ding ding ding
I get it now
What vs Why
Alias on 2008-01-22T02:37:13
POD describes for other users WHAT the code does.
Comments describe for other
maintainers WHY the code does it.
POD Alternative (sortof)
renodino on 2008-01-22T04:41:41
Pod::Classdoc
is something I whipped up after trying to provide API docs for a major project, and finding the usual POD format sorely lacking. Its POD, but
of a Javadocish nature. Intended as an adjunct to "user Guide" type POD.
