2009/5/4 Jon Lang <datawea...@gmail.com>:
> With this in mind, I'd propose two forms of '#=', based on what comes
> after the '='. If it is followed by one or more '['s, you have
> bracketed POD which is terminated by an equal number of ']'s;
> otherwise, you have POD which is terminated at the end of the current
> line. Note that I specifically said '[' rather than 'a bracketing
> character'; this is for the same reason that 'C<code>' is POD markup,
> but 'C{code}' isn't. As well, I chose '[' instead of '<' to minimize
> the need to double or triple up on the encapsulating brackets whenever
> inline POD markup is involved.
The end-of-line Pod option would be nice. I assume you mean something like this?
has $.something; #= This is an important attribute
has $!other;
However, I'm not sure why you would want to restrict the multi-line
form to only allow square brackets. The syntactically similar embedded
comments (#{}) allow almost any valid bracketing character pair, and
even Pod allows C«» nowadays.
> I'd like '#=' to follow similar rules to what '#' follows, with the
> caveat that a line beginning with '#' counts as a single-line comment
> no matter what the second character is. Specifically, having the
> second character be an = does not transform a full-line comment into a
> single line of documentation. This preserves the ability to comment
> out a series of lines by prepending a '#' to each of them without
> having to worry about whether or not any given line will start doing
> strange things. This means that '#=' can never appear at the start of
> the line if you want it to denote documentation; but anywhere else is
> fine.
That makes sense. Embedded comments (#{}) aren't allowed at the
beginning of a line either for the same reason. I hadn't thought of
that when I wrote my earlier post, so ignore what I said about
changing that bit. :)
As for a Pod parser not knowing what to do in case of "say '#='" and
such, I think we should assume that the doc tool /can/ parse Perl
(likely using STD.pm). Extracting comments (be it #, #{}, #=, or #={})
reliably from Perl code without knowing Perl doesn't seem like a
viable option. How do we know that the #= isn't inside a multi-line
string or heredoc, etc? It's easy to do with Pod blocks since they
were designed for that (i.e. = at the beginning of a line is always a
Pod directive), but since the kind of docs we're talking about here
are supposed to be tied to the code they appear next to, it wouldn't
do much good to be able to extract all the comments without
understanding the Perl code around them anyway.
