2009/11/24 Steve Bertrand <st...@ibctech.ca>: > I've noticed that the POD for several modules do not include method > usage for the functions/methods that are designed as 'internal-only'. > > I've reached a stage where not having POD for ALL of my methods is > becoming overwhelmingly cumbersome, as I have to read the code to > remember usage. > > Is there a common practice for this? If POD doesn't display internal sub > usage, where would one document it?
This documentation is clearly necessary, but not for the users of your module. What you do is document it in such a way that the users never see it, only the maintainers. There are several ways to do it. The most common is just a series of # comments. There are ways to do it in pod but without making it visible to the users: =for Rationale: This function uses Smith's algorithm instead of Jones's. Jones's is faster in the general case but Smith's performed better when benchmarked with our test dataset. =cut This pod block will not be visible to the users, because it uses the =for pod directive which means "only for the named pod translator". There is no translator called Rationale: and so no translator will read it. The =begin and =end pod directives can serve a similar purpose. Phil -- To unsubscribe, e-mail: beginners-unsubscr...@perl.org For additional commands, e-mail: beginners-h...@perl.org http://learn.perl.org/
