jds17 has asked for the wisdom of the Perl Monks concerning the following question:

Dear monks,

I am using Moo::Role for a module and want to write POD for role methods only once to avoid having multiple copies of the same POD to maintain. The natural place for this documentation would be the class defining the role, but currently I have to repeat the POD in each role impersonating class since otherwise Pod::Coverage chokes on it.

For Moose, there is Pod::Coverage::Moose which can be used to fix this, but I did not find anything similar for Moo. Do you have an idea what to use or how to handle this?

  • Comment on Does something like Pod::Coverage::Moose exist for Moo?

Replies are listed 'Best First'.
Re: Does something like Pod::Coverage::Moose exist for Moo?
by tobyink (Canon) on Oct 24, 2012 at 21:26 UTC

    Playing around with Pod::Coverage::Moose's test suite, it appears to "just work" for Moo roles. Moo is after all, designed to offer Moose-compatible classes and roles.

    Of course, Pod::Coverage::Moose has a dependency on Moose, and perhaps the whole reason you are using Moo is to avoid your project having a dependency on Moose. But in this case it shouldn't be a problem - include the pod coverage tests in the author test suite, but not in the test suite run by people installing your module.

    perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'
[reply]

      Thank you for replying again, tobyink. The reason I am using Moo(::Role) is that I want to ensure at compile time that certain classes provide a given set of methods. (For each DBMS to be supported, there is one such class handling DBMS specific things.)

      Since I wanted the module to be as portable as possible, I wanted it to have few dependencies, so Moo won against Moose.

      You are right, pod coverage is mainly of interest to the author(s) of a module, so I could leave the pod coverage tests out for distribution, but I am not completely happy with having two versions of the module.

      Maybe I will take the time and see how Pod::Coverage::Moose works and if I can borrow from there without having to use Moose. But right now I want to get the first version of the module out as soon as possible, there is only some documentation left to be written. For the time being, I think it would be wisest to follow your suggestion and leave the coverage tests out for the users.

[reply]

        You may have missed my point. You don't need to borrow stuff from Pod::Coverage::Moose, because Pod::Coverage::Moose already seems to support Moo classes and roles.

        Just use Pod::Coverage::Moose as-is, but put the tests in your xt directory instead of t. That way, MakeMaker (or whatever you're using to package your distribution) should find and run the test while it's building the distribution tarball, but the test will not automatically run on end users' systems.

        perl -E'sub Monkey::do{say$_,for@_,do{($monkey=[caller(0)]->[3])=~s{::}{ }and$monkey}}"Monkey say"->Monkey::do'
[reply]
[d/l]
[select]

Back to Seekers of Perl Wisdom