"If you declare an explicit invocant for an Array type using an array
variable..."
Suggest:
"
The invocant may be given a sigil other than the C<$> "item" sigil using the
same rules as binding variables to class types as described in S02 under "Names
and Variables". For example, if the class does the C role, it may
be declared with the C<@> "array" sigil.
Naturally, declaring an explicit invocant for an Array type lets you use it in
the usual way, such as using it in list context to produce its elements.
"
The word "self" is described as a keyword and as a function. Be stronger about
defining it. I suggest,
"
Within the lexical scope of any method, the C keyword behaves as a
function that returns the invocant in item context. It is improper to use this
pseudo-function in any manner other than to call it directly. In particular,
an implementation is not required to support taking a Capture to the function.
Note, however, that you may I it from a closure.
Also note that, as is usual with Perl, the existance of keywords do not
preclude the use of identifiers with the same name. Although this is usually
considerd bad form to make a variable named C<$if>, defining your invocant to
be C<$self> is not deemed to be in bad taste. However, defining C<@self> (or
other sigil forms other than item) could indeed confuse someone reading the
code, and is discouraged.
"
Per conversation with Audry, I suggest adding the following before "Private
methods are...".
"
Methods, like any other kind of C, behave as if defined with C by
default, if no scope modifier is used. This is described in S06 under "Named
subroutines". However, it may be desirable to use the C keyword
explicitly, as it offers the ability to put the return type before the method
name, in the C style.
"
