Iain Truskett wrote: > * Nick Pinckernell ([EMAIL PROTECTED]) [24 Jul 2003 14:50]: > > [...] > > The idea is: a structured Javadoc style system for Perl. It would be > > very dependant on multiline comments (I've seen the Perl 6 RFC). > > Why so? > > > I think this idea would be really good for Perl 6, > > because, in my opinion, POD is lacking. > > Could you please elaborate on this point? > > POD does lack many things, but why is a javadoc based system > any better?
I'd just like to say a couple things about my feelings on POD. POD is wonderful. Here's why: 1. It's simple and easy to learn. 2. It can be placed anywhere, in any kind of text, and painlessly stripped out with a one-liner. 3. It can be easily read without a special formatter. 4. It doesn't mandate anything about what it's documenting. It provides optimizations for code (eg. indenting = verbatim), but there are no special sequences telling the computer what is being documented. I'll talk about why this is a win below. 5. TOOWTDI. Basically, it's focus is simplicity. There are thousands of modules on the CPAN, and I've only seen one or two that were poorly documented. #1 is the one that did that. Because of #2, I document everything with POD. My C code, my E2 writeups (and convert them), just everything. Parrot does too. And it's easy to do; it doesn't pose any limitations on what I can use it in or for. #3 is obvious. #4 is really important. It fits Perl's culturally dynamic nature. You can write modules which don't use an OO interface, which don't even define any subs, and you document them just like you document everything else. #5: There's Only One Way To Do It. While this is opposite Perl's usual philosophy, it works well with documentation. It means that you don't (can't) get caught up in the meticulous details of formatting (which I so often do when I use LaTeX), and it forces you to focus on the content. So that's my praise of POD. Indeed, it could use a few changes. For instance, the paragraph rules could be relaxed to allow for more condensed lists, etc. But those are the details -- the thing that was so right about POD was the philosophy. Luke
