[PDX-PM] Tool for stubbing perldoc?

Eric Wilhelm ewilhelm at sbcglobal.net
Mon Apr 19 17:54:46 CDT 2004


# The following was supposedly scribed by
# Randall Lucas
# on Wednesday 14 April 2004 03:49 pm:

>Are there any tools for stubbing out the perldoc for an existing,
>non-documented module?  Preferably, I'd like in-place sub/method docs above
>each sub.
>

This doesn't quite do that, though you could modify it to read the regex from 
'tags' format (and I believe there is a module on CPAN for that.)  Once you 
get to that point, finding the correct line for inserting the stub would be 
trivial.

I always use a 'printsub' program to generate the subroutine and pod stub 
together, so haven't had the need for getting stubs into place after the 
fact.

>It seems like such a no-brainer that I must be overlooking something.
>Either that, or it's time to cobble something together with ctags+perl.

That's just what I had done the other day, though this was to generate 
documentation stubs for functions written in C for an Inline::C module.  
Beware the hardcoded $oo value (this was just meant to be a one-off.)

--Eric

-- 
"It is impossible to make anything foolproof because fools are so ingenious."
                                        --Murphy's Second Corollary

########################################################################
#!/usr/bin/perl

# tags2pod.pl turn a tags file (as created by ctags) into pod stubs for
# each function
#
# Copyright 2004 Eric Wilhelm
# License:  GPL

$file = "tags";
(-e $file) or die "cannot find $file";

open(TAGS, $file) or die "cannot read $file";
my %seen;
# FIXME: needs to be configurable:
my $oo = 'gpc'; # for OO methods (what we call our object)

while(my $line = <TAGS>) {
	chomp($line);
	($line =~ m/^!/) and next;
	if($line =~ m/^(.*?)\s/) {
		my $name = $1;
		unless($seen{$name}) {
			$seen{$name}++;
			print stub($name), "\n";
		}
		else {
			warn "skipping repeat of $name\n";
		}
	}
	else {
		warn "cannot make sense of $line";
	}
	# print "$line\n";
}

sub stub {
	my $name = shift;
	$name or die "need name";
	my $use;
	$oo and ($use = "\$$oo->");
	return("=head2 $name\n\n  $use$name();\n\n=cut\n");
} # end subroutine stub definition
########################################################################




More information about the Pdx-pm-list mailing list