in reply to Re: Worst thing you ever made with Perl
in thread Worst thing you ever made with Perl

Both of these tutorials, nice though they may be, talk mainly about how to stick one big block of documentation at the top or bottom of the whole file. For me that would be a step backwards. I'm MUCH more interested in documenting each function locally, right near the top of that function, (usually, right below the line that pulls @_ into named lexicals) like I would do with comments.

That is exactly the same. You return to code with =cut. An example: 

package My::Module;
use strict;
our $VERSION = '1.00';

=head1 NAME

My::Module - An example module

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=cut

sub new {
    ...
}

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=cut

sub as_string {
    ...
}

=back

=head1 AUTHOR

Juerd - <http://juerd.nl/>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut

[download]
I hate maintaining code that is interrupted by documentation. I prefer updating the code first, documentation later. Otherwise, I'd probably end up putting tests, real code and documentation all in one place. Awful.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Replies are listed 'Best First'.
Re: Worst thing you ever made with Perl
by jonadab (Parson) on Sep 30, 2003 at 18:15 UTC 
    =cut

sub new {
    ...
}
=item C<as_string>

    [download]

    Ah. I think that was the thing I needed to see, really. Though in my case it may be more like this... 

    sub authbox {
  my ($input, $callback) = @_;
=item C<authbox>
  authbox ($input, $callback);

  Returns two items.  The first is a string containing a hunk of xhtml
  suitable for inclusion wherever a div can legally be put (e.g.,
  inside a table cell or a paragraph).  If the user is not logged in,
  the box offers login options.  If the user is logged in, it offers a
  logout link.  $input should be a hashref containing any form input
  with keys starting with 'AUTH_'.  $callback should be a closure
  that, if passed a user id, returns a string containing a suitable
  greeting; this string will appear in the authbox.

  The second item in the returned list is the cookie string that
  should be passed to the browser, if any.
=cut
  # Rest of code for function goes here.
}

    [download]

    Currently I have roughly that form, pretty consistently, but with comments instead of POD. I want to convert it to POD. Unfortunately, I seem to be finding that the version of cperl-mode I have may not support POD properly. update:Yes it does; there was something wrong with my POD. 

    $;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/

    [download]
[reply]
[d/l]
[select]

      =item C<authbox>
  authbox ($input, $callback);

   more stuff
=cut

      [download]

      No. You need extra blank lines in order to form command *paragraphs*. And you shouldn't indent normal text paragraphs, because it gets rendered as code then. And consider merging the first two lines: 

      =item C<authbox \%input, \&callback>;

      [download]

      Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

[reply]
[d/l]
[select]

        Ewwww. Significant whitespace? You're kidding, right? I thought I dodged that bullet when I quit trying to learn Python and stuck with Perl. 

        $;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/

        [download]
[reply]
[d/l]
Re: Worst thing you ever made with Perl
by jonadab (Parson) on Sep 30, 2003 at 18:33 UTC
    I hate maintaining code that is interrupted by documentation. I prefer updating the code first, documentation later.

    If I do that, I end up with incorrect or obsolete documentation. I specifically like to see the ($foo, $bar, $baz) = @_; right above the documentation of the function's arguments, so that if I add any other optional args I see the mismatch and update the docs. 

    $;=sub{$/};@;=map{my($a,$b)=($_,$;);$;=sub{$a.$b->()}}
split//,".rekcah lreP rehtona tsuJ";$\=$ ;->();print$/

    [download]
[reply]
[d/l]
[select]

In Section Meditations