On Wed, Sep 12, 2012 at 12:01:31PM -0400, Weidner, Ron wrote:
> I'm looking at documenting perl code I'm working on. I'm considering POD but
> I don't
> think it can do what I want. Example of what I would like...
>
> [code]
>
> # here I would put POD synopsis etc.
> # here I want to put POD that describes this function
>
> sub my_echo
> {
> my ($str) = @_;
> print $str;
> }
>
> # here I want to put POD that describes this function
>
> sub my_sum
> {
> my ($x , $y) = @_;
> return $x+$y;
> }
>
> # here I want to put copywrite info etc.
>
> [/code]
>
> Can the tool be used this way? If not, any recommendations
> short of rolling my own?
("Extra" whitespace removed by me)
I'm sort of a n00b when it comes to the POD format, but I have
used it on occasion to document personal code. You can do
something like that for sure, depending on exactly what you want
from it. For example:
#!/usr/bin/perl
=pod
=head1 NAME
MyModule - My module that does something useful.
=head1 SYNOPSIS
use MyModule;
MyModule::do_something(@args);
MyModule::do_something_else(1);
=head1 FUNCTIONS
=over
=cut
package MyModule;
=item
do_something(@args)
Does something good with @args.
=cut
sub do_something {
my @args = @_;
# Do something.
}
=item
do_something_else($yes)
Does something else good when $yes is truthy.
=cut
sub do_something_else {
# Do something else.
}
=back
=cut
__END__
You automatically switch into pod format whenever you use a POD
"instruction" (that might be the wrong terminology), which begins
a "paragraph". You can switch back to Perl with =cut.
If the intent is only to have the documentation for the
subroutines right above them so they're nearby and easier to keep
in sync then I think that the Pod format will work just fine. :)
If you haven't already then you should read through `perldoc
pod', which will likely have better advice than me. :)
Regards,
--
Brandon McCaig <bamcc...@gmail.com> <bamcc...@castopulence.org>
Castopulence Software <https://www.castopulence.org/>
Blog <http://www.bamccaig.com/>
perl -E '$_=q{V zrna gur orfg jvgu jung V fnl. }.
q{Vg qbrfa'\''g nyjnlf fbhaq gung jnl.};
tr/A-Ma-mN-Zn-z/N-Zn-zA-Ma-m/;say'
signature.asc
Description: Digital signature
