Jon Lang kept his promise:
> I promised some further thoughts; here they are:
Much appreciated.
> As written, declarator aliasing attaches the alias to a piece of code,
> and draws both the name and the alias from that. What about using a
> special case of the declarator block for this? That is:
>
> class Database::Handle { #=alias
> has IO $!handle; #=alias
> my Bool method open ($filename) {...} #=alias
>
> =for para
> Note that the A<method> method of class A<class>
> stores the resulting low-level database handle
> in its private A<has> attribute.
>
> }
>
or:
> class Database::Handle { #=>
> has IO $!handle; #=>
> my Bool method open ($filename) {...} #=>
>
> =for para
> Note that the A<method> method of class A<class>
> stores the resulting low-level database handle
> in its private A<has> attribute.
>
> }
Definitely interesting ideas, especially the second one. My concern
would be that they compete
with the #= blocks which might also be needed on such declarations.
> Regardless of what syntax you use for declarator aliasing, I'd also
> recommend some sort of numbering scheme if you alias more than one
> declarator of the same type in the same lexical scope:
It's definitely an issue I hadn't considered properly. However, I
think the correct
solution is not numbering (which is always fraught with problems when subsequent
maintenance adds an extra declarator in the middle), but rather naming. Like so:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open ($filename) {...}
=alias close
my Bool method close() {...}
=for para
Note that the A<open> method of class A<class>
stores the resulting low-level database handle
in its private A<has> attribute, while the A<close>
method closes that handle.
}
I know this looks redundant. But the whole point of logical names is you
don't have to change them when the physical name changes:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open_file ($filename) {...}
=alias close
my Bool method close_and_sync() {...}
=for para
Note that the A<open> method of class A<class>
stores the resulting low-level database handle
in its private A<has> attribute, while the A<close>
method closes that handle.
}
> If you adopt the declarator block basis for declarator aliasing, you
> could even let the documenter choose his own names:
>
> class Database::Handle { #=>
> has IO $!handle; #=>
>
> my Bool method open ($filename) {...} #=>m1
> my Bool method close () {...} #=>m2
> An unrelated possibility would be to allow empty A<> tags in a
> declarator block, with 'A<>' being replaced with the name of the
> declarator to which the block is attached:
These are both very useful ideas.
I'll ponder them carefully in preparation for the next revision.
Thanks, Jon!
Damian
