G'day GrandFather,

I ran quite a few tests. I had problems reproducing your results. I initially assumed, based on the order of package statements, that your filename was based on the first package name (e.g. .../Segment.pm); if I used the second package name (e.g. .../ELF/File.pm), I got the results you indicated.

You didn't say how you were using Pod::Coverage. For my tests, I used

$ perl -I. -MPod::Coverage -e 'my $pc = Pod::Coverage::->new(package =
+> "XYZ"); print $pc->coverage ? "Y" : "N"'
[download]

where XYZ was one of ten different package names spread across five *.pm modules. Each module had two packages. I'm also using the latest (0.23) version of Pod::Coverage.

Here's a quick rundown of what I found:

• =head1 NAME ... had no bearing on the results. It could be present, absent, or even use a totally bogus name.
• The order of package statements had no bearing on the results.
• The use of package statements with or without blocks had no bearing on the results.
• POD was only considered to be related to the module filename (cf. first paragraph above).
• POD did not need to be part of a package block to be considered as covering code in that package.

I considered all tests and related code to be too much to post here; however, this last set covers most of the points I mentioned.

$ cat X5.pm
package Y5 {
sub fred { 2 }

=head1 NAME

Y5

=head2 fred

fred() returns 2

=cut

};

1;

package X5 {
sub fred { 1 }
};

1;

$ perl -I. -MPod::Coverage -e 'my $pc = Pod::Coverage::->new(package =
+> "X5"); print $pc->coverage ? "Y" : "N"'
Y

$ perl -I. -MPod::Coverage -e 'my $pc = Pod::Coverage::->new(package =
+> "Y5"); print $pc->coverage ? "Y" : "N"'
N
[download]

If your "helper classes" are acting in a similar way to _helper() private functions, I would consider POD to be an inappropriate vehicle for documenting them (in much the same was as you wouldn't have POD with =item C<< _helper() >>). If these classes are intended to be public, I would suggest putting them in separate modules with their own specific POD.

"I could move the helpers out into other module files, but that gets pretty silly for some of the helper classes."

It may be that some classes get their own modules with POD but others use embedded package statements but have no POD.

"ELF::File returns helper class objects for some purposes so it is important that their public methods are documented."

So that would be an example of the former category: separate module with its own POD.