On Sat, Apr 02, 2005 at 03:19:33PM +0800, Sam Vilain wrote:
: Luke Palmer wrote:
: >>Supposing I had a "doc" trait, could I say:
: >> sub f2c (Num $temp doc<Temperature in degrees F>)
: >> doc<Convert degress F to degrees C>
: >> {...}
: >>Or would I be forced to spell it doc('stuff') ?
: >Well, first you need an `is` somewhere in there. And after that I think
: >you'll need to do it in doc('stuff') form. If we did allow doc<>, then
: >this:
:
: A word of warning...
:
: Perldoc[*] will eventually support this sort of thing, for sure. But it
: will lead to the unfortunate side effect that your code needs to at
: least compile without syntax errors, and without too many obscene
: mistakes - so that these traits are accessible by the dialect that
: interprets them into a Perldoc tree.
It should also be pointed out that we're making the structure of the
surrounding POD available to the code. Working from that end has
the advantage of keeping cruft out of the signature, while keeping
the information close and verifiable.
: That's if you care about seeing the information presented nicely when
: you use `perldoc Foo', of course.
If we work it out right, it won't be an either/or thing. The POD
will be easily recognizable as POD (albeit with different parsing
rules than Perl 5), but at the same time it's available as data for
introspective and class-browserly purposes.
: * - the project aiming to provide dialect-agnostic inline documentation
: for Perl 5 and Perl 6. The Perl 5 prototype is on CPAN... still in
: early stages.
If by "dialect-agnostic" you mean that it presents that view to
the user, that's fine. But at minimum, the project will have to be
"gnostic" about parsing difference between Perl 5 POD and perl 6 POD.
For example, =cut is going away, and the requirements for blank lines
are being reduced. Plus there will probably be some changes to help
the computer navigate to its associated documentation, such as tagged
fields that turn into a hash value when accessed via %=POD or whatever
the interface turns out to be.
Larry
