Jonathan Lang asked:
What's the rationale for keeping POD comments that are nested in block
comments visible to the POD parser?
The rationale is that Perl 6 and Pod 6 have been designed to be completely
independent and uncoupled. That way, you can look at a piece of Pod without
worrying about any syntactic or semantic effects from the surrounding Perl
code...and look at a piece of Perl code without worrying about any syntactic
or semantic effects from the surrounding Pod. We think that's highly valuable.
The separation of Perl and Pod also makes parsing each language considerably
easier. As the two languages are now specified, the Perl parser doesn't have
to worry about embedded Pod, since it can be removed in a preprocessor stage,
or easily handled as part of the parser (since the Pod syntax is simple and
distinctive and morally equivalent to whitespace). Likewise the Pod parser
doesn't have to worry about Perl, since no Perl construct can affect the
meaning of embedded Pod. This second point is by far the more important, since
it means that the (comparatively simple) Pod parser doesn't have to have a
full implementation of a (far more complex) Perl parser within it.
The separation also means that you can--potentially, at least--use Pod to
document source in *any* language (i.e. not just Perl) provided that language
allows for a preprocessor to strip the Pod from any source before compilation.
And because Pod ignores "ambient" source code, the standard Pod parsing and
transformation tools will be able to be used, regardless of the interleaved
language.
It seems to me that the least surprising behavior would be for the POD
comment to be swallowed up by the block comment, on the basis that a
block comment ought to be equivalent to prefixing every line from its
start to end with a C<# >. Conversely, I'd expect a block comment
that's nested inside a POD comment to be passed to the POD parser as
ordinary POD text. In short, whichever kind of comment comes first
should dominate.
"Least surprise" always depends on your underlying model of a phenomenon.
My underlying model is that documentation and the source it's documenting
should be entirely orthogonal. So, to me, it would be very surprising if a
programming construct (block comments) interacted with documentation. Or vice
versa.
To put it another way:
* At the Perl 6 level, all Pod is syntactically and semantically
invisible and therefore already equivalent to a comment.
So there's no need for Perl 6 comments to interact with Pod
(since commenting out a comment is a null operation, as far as
Perl is concerned).
* At the Pod 6 level, all Perl code is merely meaningless ambient
background noise and therefore already equivalent to whitespace.
So there's no need for Pod comments to interact with Perl 6 (since
commenting out whitespace is a null operation, as far as Pod is
concerned).
For all of the above reasons, I'm strongly convinced that the total separation
of Church (i.e. documentation of belief) and State (i.e. specification of
action) is as a good thing for programming languages as it is for nations. :-)
Damian
