> On 12/23/20 4:28 PM, Ralph Mellor wrote:
> > If a method does not explicitly specify its invocant type, it is set
> > to the type of the enclosing class.
>
> But it does not specify an invocant. It just leaves it blank
This is how it works in Raku source code. If there's no signature at all,
or if the invocant is blank, or if the invocant's type is not specified, its
type is the type of the class which encloses or composes the method
(or `Mu` for a mainline `my` method).
Presuming the same for the doc maintains consistency between what
signatures look in Raku source code, and what they look like in doc.
Raku is explicitly designed with context in mind as an essential
driver for its design, and for comprehending code.
This may not work for you. But it's presumably ideal for newbies
and experts that take cues from context -- which is to say almost
all of those who I would expect to ever enjoy working with Raku.
That's not to say you can't do the work to improve things from
your perspective. Provided you don't make things worse for those
who appreciate the language (and the doc) presuming that Raku
devs will in general be happy to take context into account, you are
of course free to do, and advocate, as you wish.
> > So, the doc is fine as is for the invocant.
>
> I was not asking if you could pick it up by context with
> other things written on the page. I was specifically asking
> about the definition line.
I wasn't saying you *could* pick it up from context.
I was implying you *should* pick it up from context.
I presumed you care to learn what makes Raku Raku, including
contextual clues to which attention *must* be paid when one is
comprehending code, and which cues are also readily available
for comprehending the doc.
The context is there; why *not* pay attention to it? Why *not* learn
how Raku code works? And if you learn how Raku signatures work,
which isn't difficult, why *not* apply the exact same rules to the doc?
Imo introducing redundancy often makes sense for tutorials, but less
often, imo, for reference doc. In particular, I see blank invocants in a
method signature as an ideal way to convey that a method's invocant
type is determined by its context.
> Once you learn to read them, the definition lines can be really useful.
Yes. And you have now presumbly both learned how to read the type of
the invocant if it's blank, and learned that it's a really easy rule to learn.
> My problem is that they are often incorrect, which put a hammer into learning
> them.
I hear that.
But the response to that issue should be to correct the errors.
Manually adding redundant information will inevitably *increase*
the number of errors unless it's automated. It may also *reduce*
the doc's usability for those who do not benefit from the redundancy.
If you are willing to write good automation code to solve this doc
problem, and design doc changes to minimize the harm done for
those who do not benefit from the redundancy, and do the work
to gain consensus that the work you prepare to make this change
should be applied, and commit to doing the work to make sure it
gets properly applied, then I definitely wouldn't stand in your way,
even if I think it would be a mistake to apply such a change.
Or, if you are *not* willing to do that work, you can presumably just
acknowledge that you could resolve the problem you thought you
saw by no longer seeing it as a problem, but rather just something
you have come to learn along the way.
> > The returned value is a cosine, which, per the linked doc,
> > is a real number. The doc could perhaps show a return value
> > of Real:D.
>
> I like it!
To be clear, I'm not saying the doc *should* show that return value.
Just that it *could*, and that *perhaps* that would be appropriate,
in contrast to my opinion about the invocant type.
> This look right to me (but keep in mind I don't know what I am doing)
> method cos( Cool:D: --> Real:D )
As I hopefully made clear at the start of this email, redundantly explicitly
specifying the invocant in the signature despite it being already explicitly
specified by the enclosing context seems ill-advised to me, but if you do
the work to introduce automation of its insertion, you should be able to
make it optional, and that would work fine for me if other documenters
agree it's an acceptable thing to introduce.
love, raiph
On Thu, Dec 24, 2020 at 2:42 AM Todd Chester via perl6-users
wrote:
>
>
>
>
> >>
> >> Going back to the original question,
> >>
> >> should not the doc page say?
> >>
> >> method cos( Cool:D: --> Cool:D )
>
>
> On 12/23/20 4:28 PM, Ralph Mellor wrote:
> > If a method does not explicitly specify its invocant type, it is set
> > to the type of the enclosing class.
>
> But it does not specify an invocant. It just leaves it blank
> >
> > The `cos` method is declared in the `Cool` class, so that is its
> > invocant type.
> >
> > The doc shows that it's declared in the `Cool` class.
>
