Steve Bertrand wrote: > 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? > > Steve >
I have two levels of documentation. I have an internal one use for notes about the implementation for the maintainers of the sub. I have an external one which describes how to use the sub. Normally, I don't bother with the second unless I'm writing a module or object. I use Sub::Starter http://search.cpan.org/~shcorey/Sub-Starter-v1.0.6/lib/Sub/Starter.pm or, to be precise, the script that is installed with it, substarter http://search.cpan.org/~shcorey/Sub-Starter-v1.0.6/script/substarter to create my sub's from a usage statement and a template. I find creating a usage statement is easier that creating the sub. Example: sub -c '$text | @text = trim( @text );' This will create; # -------------------------------------- # Name: trim # Usage: $text | @text = trim( @text ); # Purpose: TBD # Parameters: @text -- TBD # Returns: $text -- TBD # @text -- TBD # sub trim { my @text = @_; my $text = ''; return wantarray ? @text : $text; } PS: If you're using ViM, you can use substarter as a filter. In ViM, enter :help filter -- Just my 0.00000002 million dollars worth, Shawn Programming is as much about organization and communication as it is about coding. I like Perl; it's the only language where you can bless your thingy. -- To unsubscribe, e-mail: beginners-unsubscr...@perl.org For additional commands, e-mail: beginners-h...@perl.org http://learn.perl.org/
