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