Documentary annotations: $what doc<why>

15 views
Skip to first unread message

Chip Salzenberg

unread,
Mar 31, 2005, 1:41:44 PM3/31/05
to Perl 6 Language
I'd like to annotate Perl 6 parameters and other entities using
traits, since that's the best way (I know of) to have them appear
immediately in the text of the program where they are.

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') ?
--
Chip Salzenberg - a.k.a. - <ch...@pobox.com>
Open Source is not an excuse to write fun code
then leave the actual work to others.

Luke Palmer

unread,
Mar 31, 2005, 7:38:22 PM3/31/05
to Chip Salzenberg, Perl 6 Language
Chip Salzenberg writes:
> I'd like to annotate Perl 6 parameters and other entities using
> traits, since that's the best way (I know of) to have them appear
> immediately in the text of the program where they are.
>
> 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:

is doc<Convert degrees F to degrees C>

Would mean:

is doc('Convert', 'degrees', 'F', 'to', 'degrees', 'C')

Which I expect is not what you intended. But if we start allowing that
everywhere, then I think that we'd have to do it for subs, too:

sub foo(*@args) {...}
foo<a b c d e>

And that isn't an implausible thing to do, but it forbids what might be
a common practice:

$foo.hash{'a'}

Replacing it with the more convoluted:

$foo.hash(){'a'}

And it essentially wouldn't allow objects that could be treated as both
subs and hashes... not that that's a huge loss. Anyway, I think you'll
have to stick with is doc('...').

Luke

Abhijit Mahabal

unread,
Mar 31, 2005, 9:24:52 PM3/31/05
to Luke Palmer, Chip Salzenberg, Perl 6 Language
On Thu, 31 Mar 2005, Luke Palmer wrote:

> Chip Salzenberg writes:
>> I'd like to annotate Perl 6 parameters and other entities using
>> traits, since that's the best way (I know of) to have them appear
>> immediately in the text of the program where they are.
>>
>> 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:
>
> is doc<Convert degrees F to degrees C>
>

But if you are going to use doc('') in a million places, can you not also
make doc a trait_verb and save a little typing? So:

role doc{
sub *trait_verb:doc($container: $string) {
...
}
}

But what do I apply the role to? perhaps
class Object does doc


Now

sub f2c (Num $temp doc "Temperature in degrees F") {...}

works(I think): trait_verb:doc is a sub, not a method, and so parens are
not needed.

It works, but that doesn't read too well. We do need a verb there. "docs",
perhaps? Or "gloss", which is both a noun and a verb?

--abhijit

Michael Walter

unread,
Mar 31, 2005, 9:42:13 PM3/31/05
to Perl 6 Language
Make "is" polymorphic :D

Michael

Ashley Winters

unread,
Mar 31, 2005, 10:58:25 PM3/31/05
to Perl 6 Language
Chip Salzenberg writes:
> I'd like to annotate Perl 6 parameters and other entities using
> traits, since that's the best way (I know of) to have them appear
> immediately in the text of the program where they are.
>
> 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') ?

Perhaps you spell it 'annotated' and add a few shortcuts?

Num $temp is annotated('Temperature in degrees F')
Num @temp is an('Array of temperatures in degrees F')
Dog $spot is a('Good Dog!')

Ashley Winters

Chip Salzenberg

unread,
Apr 1, 2005, 11:06:37 AM4/1/05
to Abhijit Mahabal, Luke Palmer, Perl 6 Language
According to Abhijit Mahabal:

> sub f2c (Num $temp doc "Temperature in degrees F") {...}

Niiiice.

Sam Vilain

unread,
Apr 2, 2005, 2:19:33 AM4/2/05
to Luke Palmer, Chip Salzenberg, Perl 6 Language
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.

That's if you care about seeing the information presented nicely when
you use `perldoc Foo', of course.

Sam.

* - 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.

Larry Wall

unread,
Apr 2, 2005, 1:13:23 PM4/2/05
to Perl 6 Language
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

Reply all
Reply to author
Forward
0 new messages