Why not play tricks with =for? It should not be difficult to modify the pod2text converter (or whatever other convert you want) to accept =for private blocks. Then you can have two converters, one for basic API information, and another for private docs. Javadocs have a similar concept, and I think it's a good idea. Getting your developers to follow it is simply a matter of corporate coding policy.

In fact, I think I should probably implement that, or track down a converter that does it already.