how about cool uses for perlDOC?

Ok ... so i'm on the testing bandwagon and all, and i've been reading ISBN 0201795264 (Perl Medic; the ISBN linker seems b0rked). in the "Rewriting" chapter, there's a note on disabling large code blocks. while most, says the author, would use:

   while (0) {
       ### nasty code mess here ...
   }
[download]

there's another way, via perldoc, to do the same.

=item comment

### nasty code here 

=end comment

=cut
[download]

it works because the POD parser doesn't do anything with the 'comment' directive.

i just thought it was cool. and another good reason to fiddle with perldoc.

Comment on how about cool uses for perlDOC? Select or Download Code

Replies are listed 'Best First'.
Re: how about cool uses for perlDOC? by hossman (Prior) on Feb 04, 2005 at 08:07 UTC
correctness of the perldoc asside, there are two very differnet use cases here. In the first case, you want to disable the code and keep it from ever running, but it will still be parsed and validated for syntactic (and semantic) correctness. This can be very advantagous when you want to temporarily disable some code, but you don't want anyone to move, remove, or refactor variables or functions that it calls. In the second case, by making the lines perldoc, their content is irrelevant, and you're free to do whatever you want. Frankly, if you are using a decent text editor or IDE, it should be trivial to comment out a large number of lines with a simple macro, and it should be jsut as simple to uncomment then later. And i find it a lot easier to spot at a glance when a large chunk of code is commented out then to tell when a large chunk of code is "poded out". Even when I'm working with java, which supports both a prefix comment marker, and a delimiting comment marker, i always use the prefix comments to comment out a large chunk of code. that long column of comment characters really jumps out at you.	[reply]
Re^2: how about cool uses for perlDOC? by ff (Hermit) on Feb 17, 2005 at 14:09 UTC
While I recall that the perldoc verbiage (and verbiage elsewhere?) generally frowns on using pod to comment out sections of code, I still use it anyway. (I don't use pod to embed documentation in my code so the two uses don't conflict.) It's just very easy to embed `=pod print "Hello World\n"; =cut` [download] and hopping to the start or beginning of a block of commented-out code is as easy as searching for `=pod` or `=cut`. Vim colors the comment in blue so that it stands out quite nicely from live code. Inserting `#` symbols easily disables these marks when necessary.	[reply] [d/l] [select]
Re^3: how about cool uses for perlDOC? by ff (Hermit) on Feb 27, 2005 at 04:15 UTC
Hmm, while browsing things about vim I came upon an excellent article about using vim with perl http://mamchenkov.net/blog/item/vim_for_perl_developers which mentioned a tool to add to your plugins folder (the BlockComment plug-in by Chris Russell). Basically, by highlighting a block of text with your mouse, you can comment that block while preserving its indentations by doing a .c and you can toggle off the comments by highlighting the text and doing .C	[reply]
Re: how about cool uses for perlDOC? by ambrus (Abbot) on Feb 03, 2005 at 19:42 UTC
That doesn't seem to work. Perdoc does parse that. You'll have to use `=begin comment nasty code here =end` [download]	[reply] [d/l]
Re^2: how about cool uses for perlDOC? by geektron (Curate) on Feb 03, 2005 at 21:10 UTC
hrm. strange, because i used it earlier today, and it worked just fine. and that's straight out of the book. perhaps a difference in the POD parsers ... dunno.	[reply]
Re^3: how about cool uses for perlDOC? by ambrus (Abbot) on Feb 03, 2005 at 21:17 UTC
Don't use "=item"s outside of an "=over" ... "=back" region. from perlpod	[reply]