On Mon, 21 May 2007 19:27:26 -0400 James E Keenan <[EMAIL PROTECTED]> wrote:
> Mark Glines wrote: > > > > Think its worth adding a > > codingstd test for POD coverage? > > > > > > No. > > Or perhaps: No, not unless you want to start a big "philosophical" > argument about POD coverage. > > I say this as someone who dissents from the prevailing wisdom about > POD coverage as it relates to CPAN modules. That's because the tests > on CPAN that purport to rate the "kwalitee" of the POD coverage of > CPAN distributions will only credit you if you write your POD in one > particular style. If you happen to have written POD for one of your > distros before that standard was formulated, or if you happen to > think that style doesn't suit your distro well, then you don't get > credit and your "kwalitee" sinks. > > There are distros for which I've written 40+ pages of documentation > but which fail these "kwalitee" tests because of the way I structured > the =head tags. > > I happen to think that some of our coding standards amount to > excessive nitpicking ... and when Perl::Critic is applied to some of > the code I maintain, the results, IMHO, are demonstrably less > readable code. And that's for stuff we write in relatively well > structured languages like Perl 5 and PIR. We write POD in English; > need I say more? > > Finally, to add a test for POD coverage is just one more test which > will fail often in 'make test' or 'make smoke' and yet say nothing > about the quality of Parrot. > > In, short: No. Ok. Thanks for the feedback. Lets see what I can do with it... First. Frankly, I don't care about the *style* of POD in use, just that there *is* some. "Well-formedness" for me comes down to parsability, not style. So Perl::Critic can GTFOMI. :) And there already is a POD well-formedness test (t/doc/pod.t), so all the codingstd test I'm proposing would do is make sure some pod exists, at least for non-generated sources in POD-capable file formats. I feel the same way you do about Test::Pod::Coverage; its the reason I haven't added POD coverage tests to my own distributions. It's quite possible to document a module properly without having a separate =head tag for each subroutine in it. Second. How do you feel about a codingstd test for this that is not run during "make test" or "make smoke"? The @coding_std_tests variable in t/harness looks to me like a whitelist for which tests to run on non-release builds... so if this test isn't part of the list, then everyone is happy? (Or have I misunderstood that code?) If you still don't like it, I'll drop the subject :) Mark
