Without replying to anyone in particular, I'll say ...
I agree with the camp that says an = at the start of a line is pod,
without exception, regardless of context.
I am also assuming that "start of the line" means there is no
whitespace to the left of the =.
I also recognize and agree with Perl 6 being sometimes whitespace sensitive.
I also found from my own experience a few months back (and I added a
test for it as t/syntax/parsing/pod_in_multi_line_exprs.t), that this
(represented with Pod 5) didn't work, but ought to (assume the 'my'
et al is flush left):
my $list = {
=pod foo docs
=cut
'foo' => sub {...},
=pod bar docs
=cut
'bar' => sub {...},
};
For technical reasons, I was constructing a bunch of routines
anonymized within a hash, rather than added to a package. A whole
file could be mostly a single hash declaration like this. I had been
expecting that I could put pod at the start of any line and it would
work, as is what seems the most intuitive. The camp that I support
would make this work.
Given this, there is an obvious (to me) solution for pod blocks in
the middle of expressions like:
my $foo
= $bar;
As the example shows, and I believe best practices espouse, you
*indent* the code line with a leading =.
This both makes the Perl code easier to understand (a continuation is
indented), and because there is leading whitespace, that = isn't
confused with pod, which is always not indented.
Simple.
And since Perl 6 does consider whitespace significant sometimes, this
is not unprecedented.
-- Darren Duncan
