I'm jumping in on an old conversation because I only just had time to catch
up last night. I have a few questions that I think are probably still
pertinent.
On Sun, Aug 16, 2009 at 4:26 PM, Damian Conway <dam...@conway.org> wrote:
>
> Executive summary:
>
> * Pod is now just a set of specialized forms of Perl 6 comment
>
> * Hence it must always parsed using full Perl 6 grammar: perl6 -doc
>
>
This one seems relatively obvious, so it's probably been proposed. I skimmed
a few of the responses and didn't see it, but that means little, I'm sure.
This makes me wonder about other languages. I've been known to use POD in
strings within other languages that lack a facility for documenting a
program as a facility rather than as a collection of elements (which is the
javadoc et al. trap).
Should there be an explicit way to step this down to just parsing the bits
that are called out as pod? For example:
#!/bin/sh
#=notperl :leading<#> :trailing<\n>
cd $1
#=head1 ...
# ...
#=cut
Obviously causing leading #s to be stripped when evaluating the podishness
of a section of the program, up to the next newline. Similarly a CDATA block
in XML might specify (on its own line) #=notperl :lang<xml> :leading<< <!--
>> and :trailing<< --> >> as the begin and end tokens of potentially valid
POD sections. The evaluation of each identified section then being gated on
the presence of a following = token. I can't think of a language that can't
support POD in this way, but I'm sure someone will provide an example ;)
Actually, in retrospect vanilla C89 might be problematic. I seem to remember
that C9X introduces // so it could pull this off. I can imagine a messy
solution in C using #define, but it would produce compile-time warnings in
some compilers.
Interestingly, this would have the side-benefit of making any program in any
language into valid Perl code, given the appropriate notation at the start
of the program... Kind of nifty if not strictly a practical benefit.
[...]
> * In addition to delimited, paragraphed, and abbreviated Pod blocks,
> documentation can now be specified in a fourth form:
>
> my $declared_thing; #= Pod here until end of line
>
> sub declared_thing () { #=[ Pod here
> until matching
> closing bracket
> ]
> ...
> }
>
There is no explicit mention in the document as to what happens at the Perl
level when the closing bracket is reached at a point that is not the end of
a line (i.e. it is not followed by whitespace that contains a newline
character). Here's an example:
my $a #-[stop the presses!] = 4;
I'm not sure that I even think this is a good idea (nor a bad one, for that
matter), but the documentation does not make this clear. It seems likely
that the expected behavior is for Perl to treat the # as the start of a
comment, even though it encounters parsable pod thereafter, and to continue
to process the remaining part of the line as a comment, however this brings
multi-line bracketted POD into question:
sub fly($like, $to, $spirit) #=[
time keeps on slippin'
] { # error - this brace is not considered code?
...
}
fly(:like('eagle'), :to('sea'), :spirit('carry me'))
>
> * This new declarator block form is special. During source code parsing,
> normal Pod blocks are simply appended into an array attribute of
> surrounding Comment object in the AST (which is just $=POD, at the
> top level). However declarator blocks are *also* appended to the
> .WHY attribute of the declarator at the start of the most recent
> (or immediately following) line.
>
I'd very much like to establish that at default optimization levels for
execution, this information is not guaranteed to be maintained past the
creation of the AST. This allows optimizations which might place declared
elements into types which cannot maintain additional data (e.g. a Parrot
I-register). Perhaps in some cases we would want to provide such guarantees.
I wouldn't be opposed to an explicit way to request such a guarantee. For
example:
sub junk($things) is documented
#= junk happens
{ ... }
Now, even if junk is inlined and optimized away, we guarantee that its
documentation will continue to be stored in some way that can be retrieved.
This might even prevent certain classes of optimizations, but that's
implementation specific.
> * Hence, they can be used to document code directly, which
> documentation can then be pulled out by introspecting either
> $=POD or the declarators themselves. Documented declarators
> look like this:
>
Although it's something that could be added on after-the-fact, I think it's
worth calling for this up-front: All of your comments about .WHY seem to
indicate that it behaves recursively, walking the tree and pulling out any
documentation for child nodes. That's fine, but there really should be a
user-accessible and well defined way to limit that search to just the node
in question. Either through the use of an optional parameter to the WHY
accessor or a separate accessor method (given that this involves reserving
method namespace, I'd probably prefer an optional parameter).
