in reply to Easily catalog subroutines with a synopsis comment

It's mainly a matter of style I guess. Having it easy to grep through files can be important indeed. I got other projects which are slowly ported to C++ and originally had a coding style where a grep '^funcname' * -r worked nicely.

With the new coding style, where the return type is on the same line as the function name, that isn't that easy anymore.

As much as I see that this is a nice style, as much I fear duplication of documentation. I usually document every function/method (that belongs to the public API), with an extensive pod comment, which results in a nice pod documentation. I don't think I could justify the, most of the time, duplicated effort of making a pod and a comment documentation. Just for grep.

Maybe there should be a tool that greps the code and extracts the documentation for every function instead. A podgrep tool, usage like this: podgrep <subroutine name> and would print out every found pod documentation for that sub.

Just my 2 cents :)

  • Comment on Re: Easily catalog subroutines with a synopsis comment

Replies are listed 'Best First'.
Re^2: (podgrep) Easily catalog subroutines with a synopsis comment
by tachyon-II (Chaplain) on Apr 21, 2008 at 04:15 UTC

    For your enjoyment podgrep 0.01. Stick it in your path. Defaults to cwd. 

    #!/usr/bin/perl
use strict;
use Pod::Find;
use Pod::PlainText;
use IO::String;

die "Usage $0 <sub name> <dirs>\n" unless @ARGV;

my $sub = shift @ARGV;
my @dirs = @ARGV ? @ARGV : ('.');
print "Searching for $sub in @dirs\n";
my %pods = Pod::Find::pod_find( {-verbose => 0}, @dirs );

for my $file ( keys %pods ) {
    open my $fh, $file or die "Can't read $file $!\n";
    local $/ = "\n=";  # split into pod paragraph chunks
    while (<$fh>) {
        next unless m/^(\w+).*\b$sub\b/i;
        chop;
        s/^(\w+)/=head1/;  # kludge to fix parser issue with isolated 
+tokens
        print "\n-----$file\n";
        my $io = IO::String->new($_);
        Pod::PlainText::pod2text($io); 
    }
}

    [download]
[reply]
[d/l]

In Section Meditations