Methods, routines, subs misnamed on Cool page

[MorayJ]

The problem

In https://docs.perl6.org/type/Cool some routines are titled method when they have a sub as well (eg method exp). This should be a routine as it is not specifically a method. There are others.

Moritz confirmed on #perl6 "Routine is the parent class of Sub and Method" and that if only a method, it should be method name, if only a sub it should be sub name and if both routine name

Suggestions

Edit to reflect the above convention.

[MorayJ]

Potentially a bigger issue here... when I look at https://docs.perl6.org/type/Complex.html, it lists all the routines under 'Methods' even though that list contains a sub.

Some classes have a header 'Methods' because they're all methods. But what should the layout be for consistency? Everything under 'Routines' with just 'method name' or 'sub name' or 'routine name'. Or separate headers for each -> Methods, Subs, Routines?

FWIW, I prefer the idea of everything under 'Routines'

[JJ]

Um, tricky one. Since we are talking about a class, in general "methods" is used. I don't know if there's some generation magic involved, there might be, but in any case, changing it to "routines" if there are some subs would make everything a bit more confusing. While in general I agree with you that we should take care a little bit more about this, I'm worried about the implications.

[MorayJ]

I'm not sure it's consistent as it is, or I'm not clear on why there are routines and subs when there are...

[jnthn]

if only a method, it should be method name, if only a sub it should be sub name and if both routine name

Tread carefully here: there are numerous cases where things exist as both a method and a sub, but have entirely different signatures. Take map, for instance, which:

• As a method takes the first (invocant) argument as the data and the second argument as the mapper
• As a sub takes a first argument which is the mapper and then slurps the rest of the arguments as the data

In many other cases, the sub is simply dispatching to the method, rather than doing the operation itself.

[MorayJ]

So, in the case of a) Method and sub, entirely different signatures: Is that a sub and a method documented separately? Or does it have an effect on if that's called a method or a routine?

In b) The sub is dispatching to a method: Is that a method or a routine? They seem to be routines for the Cool class page (link below)

An example I am struggling with on Cool https://docs.perl6.org/type/Cool: Method uniprops is only defined as: sub uniprops(Str:D $str, Stringy:D $propname = "General_Category") I would want to call that sub uniprops.

I don't know whether, on the same page, routine Eval is supposed to have the sub and the method separated as it is for a reason like your a/b above.

Another issue is that this whole list of a mix between methods and routines (and maybe uniprops as a sub) is headlined "Methods". In https://docs.perl6.org/type/Date the headlines separate Methods and Functions.

Classes seem to inherit routines rather than methods, which is interesting.

Any help with shining a light on what is my ignorance and what might be style inconsistencies is very welcome.

[MorayJ]

I probably made this too general with my first comment on the issue. I think there might be a bigger issue to come off the back of this, but I'm going to rein this in to the original issue and just name routines in the Cool page to moritz' rule as I don't think there's any magic there and these are just minor changes.

[JJ]

I am reopening this. There are several problems. Some definitions, like sub trim, simply do not exist in the source. They are in Str, with another definition, so it's arguable we should split sub and method and take it somewhere else (and change headers if we do). Even if we decide to keep them here, the definition is not exactly right, since it includes no coercion so it should be moved somewhere else. It's probably less cumbersome to keep them where they are, but we should also add examples of sub usage in that case, using real Cool examples.