Larry Wall said:
> John Porter writes:
> : So, are you saying that if this RFC is implemented, POD would be
> : an good way to comment code?
> It already is, as far as I'm concerned.
Please, if I'm missing something specific please explain it to me. But
here's what I can tell from the documentation included with my download of
Perl:
>From perlpod by Larry Wall
The "=pod" directive does nothing beyond telling the compiler to lay
off parsing code through the next "=cut".
...
For, begin, and end let you include sections that are not interpreted
as pod text, but passed directly to particular formatters.
...
The paired commands "=begin" and "=end" work very similarly to "=for",
but
instead of only accepting a single paragraph, all text from "=begin" to
a
paragraph with a matching "=end" are treated as a particular format.
Okay, what this means to /me/ is that I can escape from the normal
interpretation of POD by using these commands (ie =for/begin/end). However
this assumes, as I read it, that we are already in POD: such as, formally:
=pod
=begin multiline comment
...disabled code or whatever
=end multiline comment
=cut
or (from perlsyn) you could get away with the following, though Tom warns
"You probably shouldn't rely upon the warn being podded out forever. Not all
pod translators are well-behaved in this regard, and perhaps the compiler
will become pickier."
=secret stuff
warn "Neither POD nor CODE!?"
=cut back
This is not what I am after! Here's what I would propose: a quick, easy to
recognize, logical to learn, way of explicitly defining where a comment
starts and ends (which requires the delimiter be unlikely to appear in the
comment itself). It would be even better if it supported nesting (which =cut
doesn't because it ends all POD).
--Michael
