I like the idea of checking on existing documentation---which would allow repeat usage as a given script evolves without stepping on yourself as it were. Might also be tweaked to indicate incomplete documentation as well, i.e. skeleton generated but still not fleshed out.
Also nice to see what others are doing about the common problem. --hsm > -----Original Message----- > From: Eric Wilhelm [mailto:[EMAIL PROTECTED] > Sent: Monday, August 16, 2004 3:32 PM > To: [EMAIL PROTECTED] > Subject: Re: Where do people learn how to document a module? > > # The following was supposedly scribed by > # Hugh S. Myers > # on Monday 16 August 2004 08:58 am: > > > I'm > >working on a script using B::Deparse that will when done at least > generate a > >skeleton document framework for subs and globals. > > That would be convenient if it can detect where documentation already > exists. > > My solution to the problem is more of a methodology. I always use a > 'printsub' script (":r! printsub -d foo" in vim) to generate a subroutine > framework with a documentation skeleton attached to it. > > I use '=head' and '=cut' as foldmarkers in vim, so having at least the > skeleton of the documentation is integral to the way I work when writing a > module. > > I haven't really prepared this for release (it could do with a good dose > of > configurability), but here's the current version to illustrate the above > points. > > --Eric > -- > #!/usr/bin/perl > > use Getopt::Long; > Getopt::Long::Configure("bundling"); > > GetOptions( > "d|doc" => \$pod, > "p|pod"=>\$pod, > "obj=s" => \$obj, > "l|lead" => \$lead, > "new=s" => \$new, > ); > > @names = @ARGV; > $obj && ($obj = '$' . $obj . "->"); > if($new) { > $obj =~ s/->/ = /; > $obj .= $new . "->"; > @names or (@names = ("new")); > } > unless(@names) { > print "Enter list of names\n"; > @names = split(/\s/, <STDIN>); > } > > # here's what I want it to look like: > my $usage = <<'EOS'; > my $code = 0; > if(@_) { > $code = 1; > warn("\n ABORT! ", join("\n", @_) , "\n\n"); > } > my $caller = $0; > $caller =~ s#.*/##; > my $string = "usage:\n $caller <>\n"; > if($code) { > warn "$string\n"; > } > else { > # $string .= $hopt->help_string; > print "$string\n"; > } > exit($code); > EOS > > my $obj_method = <<'EOS'; > my $caller = shift; > my $class = ref($caller) || $caller; > my $self = [EMAIL PROTECTED]; > bless($self, $class); > return($self); > EOS > > > $lead && print "#"x72,"\n"; > foreach $name (@names) { > my $extra = ""; > my $other = ""; > $pod && (print "\n="."head2 $name\n\n $obj$name();\n\n="."cut\n"); > if($name eq "usage") { > $extra = $usage; > } > elsif($obj) { > $extra = "\tmy \$self = shift;\n"; > if($name eq "new") { > $extra = $obj_method; > } > } > print "sub $name {\n$extra} # end subroutine $name definition\n", > $other, > "#"x72,"\n"; > }
