I promised some further thoughts; here they are:
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.
}
The rules for what gets aliased would be the same as the rules for
what gets annotated. This is more compact than the "=alias directive
sans arguments" approach, as you can put the alias on the same line as
the declarator to which it is bound.
The downside is that it runs opposite to what declarator blocks
usually do: instead of attaching some Pod to the ambient code, it
attaches a piece of the ambient code to Pod. That, and "alias" is
appearing in the declarator block where the Pod parser would be
expecting content. Perhaps you could use some other symbol to
distinguish a declarator alias from a declarator block: e.g., #=>
represents a declarator alias, while #= represents a declarator block.
So:
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.
}
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:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias
my Bool method open ($filename) {...}
=alias
my Bool method close() {...}
=for para
Note that the A<method1> method of class A<class>
stores the resulting low-level database handle
in its private A<has> attribute, while the A<method2>
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
=for para
Note that the A<m1> method of class A<class>
stores the resulting low-level database handle
in its private A<has> attribute, while the A<m2>
method closes that handle.
}
This would be more robust, in that you could rearrange the components
of the block without getting the aliases mixed up. It might even be
worthwhile to make the names mandatory.
You might even allow a second parameter which could (for example) be
used to engage in introspection of the attached thing, thus allowing
you to alias aspects of it other than its name. But I'd consider this
to be part of the Pod extensibility, rather than a core feature. An
example:
my Bool method open ($filename) {...} #=>m1
#=>m1-type Type
=para A<m1> is a A<m1-type>.
Result:
C<open> is a C<method>.
--
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:
class Database::Handle { #=[the A<> class handles a database.]
has IO $!handle; #=[the A<> attribute identifies the database
to be handled.]
my Bool method open ($filename) {...} #=[the A<> method opens
the database.]
}
This would attach "the C<Database::Handle> class handles the
database." to class Database::Handle, "the C<$!handle> attribute
identifies the database to be handled." to $!handle, and "the C<open>
method opens the database." to method open.
--
Jonathan "Dataweaver" Lang
