Here's what I do:
#+------------------------------------------------------------------------------
# NAME:
#
#
# PURPOSE:
#
#
# INPUTS:
#
#
# ROUTINES CALLED:
#
#
# OUTPUTS:
#
#-------------------------------------------------------------------------------
jack
On Sep 13, 2012, at 10:57 AM, David Precious <dav...@preshweb.co.uk> wrote:
> On Wed, 12 Sep 2012 12:01:31 -0400
> "Weidner, Ron" <rweid...@idexcorp.com> 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
> [...]
>
> Of course you can; that's almost exactly how most POD is written.
>
> Look at nearly any half-decent module on CPAN, or see perldoc perlpod -
> it even has examples.
>
> They key is that =cut ends POD, and POD directives restart it.
>
> e.g.
>
> =head1 NAME
>
> Badger
>
> =head1 SYNOPSIS
>
> my $badger = Badger->new;
> if ($badger->alive) {
> warn "Can't provision on a live badger, that's cruel";
> } else {
> $badger->provision( os => 'Linux')
> }
>
> =head1 METHODS
>
> =over
>
> =item provision
>
> Performs provisioning of this badger.
>
> =cut
>
> sub provision {
> my ($self, %args) = @_;
> ...
> }
>
> =item alive
>
> Checks whether this badger is alive.
>
> =cut
>
> sub alive {
> my $self = shift;
> return $self->has_pulse;
> }
>
> ... etc.
>
> (Hopefully you get the idea.)
>
>
>
> --
> David Precious ("bigpresh") <dav...@preshweb.co.uk>
> http://www.preshweb.co.uk/ www.preshweb.co.uk/twitter
> www.preshweb.co.uk/linkedin www.preshweb.co.uk/facebook
> www.preshweb.co.uk/cpan www.preshweb.co.uk/github
>
>
>
> --
> To unsubscribe, e-mail: beginners-unsubscr...@perl.org
> For additional commands, e-mail: beginners-h...@perl.org
> http://learn.perl.org/
>
>
--
To unsubscribe, e-mail: beginners-unsubscr...@perl.org
For additional commands, e-mail: beginners-h...@perl.org
http://learn.perl.org/
