In Java, there are four levels of access: public, package, protected, and private. In Perl, there are effectively two: public, and leading-underscore-private. Unfortunately, the leading underscore is generally understood to mean won't-be-used-outside-this-file, and just because you can break this convention doesn't mean it's a good idea.

In putting together multi-module distros, I have lots of methods, variables, and whole classes which have to be accessed by other classes, and so shouldn't get the leading-underscore treatment -- but they aren't part of the public API. In Java, these would get tagged as package or protected as part of the declaration, making the code self-documenting. Since Perl imposes fewer rules, the only way to indicate that such a component isn't public is to document it as such explicitly.

I'd like to use POD to document these components, but if something's in POD and it doesn't have a leading underscore, the implication is that it's public. So what are the alternatives?

Mark every single component with its access level in the POD? That's verbose, messy and hackish. Nobody does this, for good reason.

Document only with comments? But POD is so much better for long explanations.

Surround =headX tags with =begin comment and =end comment? What a waste of space.

The only thing that seems to make sense is to use =begin comment and =end comment to surround the docs and omit =headX ... =cut. This breaks POD::Coverage, which I don't like at all. Also, this stuff really does belong in extracted documentation -- just with an indication that the documentation is for developers, not users.

Who's got a better way?