in reply to Inline POD vs. EOF POD

I'll have to go with the rest of the posts here and suggest that inline POD is better.

Actually, since you're documenting your subs anyway (you are, aren't you? ;), what's the point of using # when the alternative (POD) is machine readable? Using CPAN modules nota bene, you don't have to make up your own doc-to-HTML-or-whatnot standard like in so many other languages.

The one disadvantage I can see would possible be performance, but I think it's kind of easy on the parser to skip POD markup as opposed to making sense of Perl code :)

These are my templates for documenting properties and methods: 

=head2 ppp

The what that is this and that.

=cut
sub ppp { my $self = shift;


=head2 mmm()

Do this, do that.

Return 1 on success, else 0.

=cut
sub mmm { my $self = shift;

[download]

/J

Replies are listed 'Best First'.
Re: Inline POD vs. EOF POD
by Abigail (Deacon) on Jul 10, 2001 at 00:35 UTC
    Actually, since you're documenting your subs anyway (you are, aren't you? ;), what's the point of using # when the alternative (POD) is machine readable?

    My, the existance of the podlators of course!

    Here's some example block comments (and the matching code that is being commented) I wrote when implementing chmod in Perl. 

                # BSD documentation says 'X' is to be ignored unless
            # the operator is '+'. GNU, HP, SunOS and Solaris handle
            # '-' and '=', while OpenBSD ignores only '-'.
            # Solaris, HP and OpenBSD all turn a file with permission
            # 666 to a file with permission 000 if chmod =X is
            # is applied on it. SunOS and GNU act as if chmod = was
            # applied to it. I cannot find out what the reasoning
            # behind the choices of Solaris, HP and OpenBSD is.
            # GNU and SunOS seem to ignore the 'X', which, after
            # careful studying of the documentation seems to be
            # the right choice.
            # Therefore, remove any 'X' if the operator ain't '+';
            $perms =~ s/X+//g unless $operator eq '+';


                    # We know the operator eq '+'.
                    # Permission of `X' is special. If used on a regul
+ar file,
                    # the execution bit will only be turned on if any 
+of the
                    # execution bits of the _unmodified_ file are turn
+ed on.
                    # That is,
                    #      chmod 600 file; chmod u+x,a+X file;
                    # should result in the file having permission 700,
+ not 711.
                    # GNU and SunOS get this wrong;
                    # Solaris, HP and OpenBSD get it right.
                    next unless -d $file || grep {$orig {$_} & 1} @ugo
+;

    [download]
    Should all of that appear in the manual page? No, of course not. This is the "matching" POD: 
    =item B<X>

The execute permission bit, but only if the target is either a directo
+ry,
or has at least one execution bit set in the unmodified permission
bits. Furthermore, this permission is ignored if I<operator> is either
B<E<45>> or B<E<61>>.

    [download]

    -- Abigail

[reply]
[d/l]
[select]
Re: Re: Inline POD vs. EOF POD
by lachoy (Parson) on Jul 09, 2001 at 19:28 UTC

    Of course I'm commenting subs! :-)

    One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate. OTOH, you can do something like:

    =begin todo

Please change the variable names to something less cryptic. Anyone?

=end todo

    [download]

    I've been meaning to play around with the nifty-looking Pod::POM module which would make data gathering easy for stuff like this -- for instance, finding out all the TODO items for multiple projects at once.

    Chris
    M-x auto-bs-mode

[reply]
[d/l]
      One note: There is, sometimes, a need to comment subroutines using '#' and not in POD. For instance, if you want to write notes to yourself or other coders (as opposed to users) about extremely specific TO DO items or whatnot, '#' comments can be more appropriate.

      Very true. My personal guideline is this:

      • Interface - POD
      • Implemenatation - Perl comment
      /J
[reply]

In Section Meditations