Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Re: Inline POD vs. EOF POD

by Abigail (Deacon)
on Jul 10, 2001 at 00:35 UTC ( #95148=note: print w/ replies, xml ) Need Help??


in reply to Re: Inline POD vs. EOF POD
in thread Inline POD vs. EOF POD

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


Comment on Re: Inline POD vs. EOF POD
Select or Download Code

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://95148]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (9)
As of 2015-07-07 23:53 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The top three priorities of my open tasks are (in descending order of likelihood to be worked on) ...









    Results (93 votes), past polls