NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.
All the Perl that's Practical to Extract and Report
I pour myself a cup of strong coffee. :-)
-- Jarkko Hietaniemi
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.
The root problem is interspersing code with POD (Score:1)
I have to say, I find the whole idea of POD interspersed with code quite loathsome. It appreciate all the reasons why it's a Good Thing (which boils down to keeping the docs as close to the code as possible), but it has so many drawbacks.
Most notably, it makes it hard to skim through the code when there's big globs of POD getting in the way. If I'm reading the source then it's code I want to concentrate on. If it's the end-user documentation that I want then I'll use perldoc or look at an HTML version
Re:The root problem is interspersing code with POD (Score:1)
This is the most salient criticism of interspersed POD, in my mind. I spend a lot of time thinking about how to organize prose -- especially technical prose -- and the only case where interspersed POD reads naturally is solely API documentation.
Reply to This
Parent