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
+;
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>>.
-- Abigail
