* Damian Conway ([EMAIL PROTECTED]) [070622 09:02]:
> Mark Overmeer wrote:
> >Then, when you want to add some docs to the method, to help the
> >correct use, add it, for instance like:
> >
> > method isValidPostalCode(str $postalcode) returns bool {...}
> > ` Check wether the postal code confirms to the standards
> > `$postalcode: a string with blanks trimmed.
> > `return: the string is not cleaned-up.
> >
> >or maybe (exact syntax open to discussion)
> >
> > method isValidPostalCode(str $postalcode) returns bool {...}
> > #= Check wether the postal code confirms to the standards
> > #=$postalcode
> > #= a string with blanks trimmed.
> > #=return
> > #= the string is not cleaned-up.
>
> Would the following syntax suffice?
>
> method isValidPostalCode(str $postalcode) returns bool {...}
> =PURPOSE Check weather the postal code confirms to the standards
> =ARG $postalcode
> a string with blanks trimmed.
> =RETURN
> the string is not cleaned-up.
>
> Because you can already do precisely that in the current design of Pod 6.
This is syntactically what can be done with the current design,
but is semantically very different.
> And having done it, the current Pod::Parser will extract all of that
> information (including the source code), preserving the sequential and
> hierarchical relationships, and present you with an internal object
> representation that your documentation tool can then analyze and
> convert to whatever content and layout you prefer (including
> non-semantic Pod that you can then feed into any of a dozen
> back-ends).
Besides the point that I do not really like the YELLING all the time, it
still has the complication to reconstruct Perl code from the Pod::Parser
tree. The tools I wish for need to able to match the tree created by Perl
with the tree created by your Pod::Parser, in some safe and simple way.
The needs for my kind of documentation gerenators are very simple: the
Perl6 parser needs to collect all lines of docs which follow a certain
line with code into the AST node of that line or item. The Perl6
parser itself doesn't need to do anything more than that. Tools doing
introspection on the AST do the rest.
You gave the hint that comments are also in the parse tree. So, that
is suffiencent for me:
sub greetings() { say "Hello, World!" }
#= the standard first program <-- doc for user
# we like Perl6 new features <-- additional doc on internals.
or
#=sub greetings
#= the standard first program
sub greetings() { say "Hello, World!" }
# we like Perl6 new features <-- additional doc on internals.
[ I think that the doc block should always start with the item
what you are describing, so if the block is before the item (or
anywhere else in the file), then it needs to be referenced to (as
simple as possible) ]
[ now I have to study the introspection features of the AST ]
--
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
