> 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 <perl6-us...@perl.org> 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. > > > > 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. > > Once you learn to read them, the definition lines can be really > useful. My problem is that they are often incorrect, which > put a hammer into learning them. > > > 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! > > This look right to me (but keep in mind I don't know what I am doing) > method cos( Cool:D: --> Real:D ) > > These two look wrong to me: > method cos() > method cos( --> Cool:D ) or --> Real:D > > Thank you for the wonderful explanation. > > -T
