I have some 36 Perl modules to document, with one subroutine in them each. This particular project is for my use only, but it should be documented for my sanity (and so Devel::Cover likes me better).

I was planning on adding stub documentation automatically, but then I realized I could have it prompt me for the documentation. This code tries to see if a subroutine is already documented, but not with Pod::Coverage.

If nothing else like this exists and there is sufficient interest, I might expand it into a real module to help build documentation.

Warning: This code does not make backup copies.

#!/usr/bin/perl

use strict;
use warnings;
use PPI;

foreach my $filename (@ARGV) {
    print "Opening up $filename...\n";
    my $doc = PPI::Document->new($filename);
    foreach my $sub (@{$doc->find('PPI::Statement::Sub')}) {
        my $subname = $sub->name;
        my $previous = $sub->previous_sibling;
        $previous = $previous->previous_sibling while $previous && !$p
+revious->isa('PPI::Token::Pod');

        if($previous && $previous->isa('PPI::Token::Pod') && $previous
+->{'content'} =~ /=(?:head\d|item)\s+$subname/i) {
            print "skipping $subname; already documented\n";
            next;
        }
        my $pod = PPI::Token::Pod->new;
        print "Enter documentation for $subname (ctrl+D when done, lea
+ve blank to skip):\n";
        my $text = join '', <STDIN>;
        $text =~ s/^\n+|\n+$//g;
        unless($text) {print "skipping $subname; no text provided"; ne
+xt}
        $pod->{'content'} = "=head2 $subname()\n\n$text\n\n=cut\n\n";
        $sub->insert_before($pod);
    }
    print "Writing code to $filename...\n";
    $doc->save($filename);
#     print $doc->serialize;
}
[download]