Unify differences between multi and multi sub

[trosel]

Some code is like:

multi sub hello($name) {say "hi $name"}

Other code is like:

multi hello($name) {say "hi $name"}

I'm not sure what is going on here, but this is something that should be decided upon. I think multi sub makes sense because you always clarify multi method in classes. And yet, I've never seen a proto sub. I've only seen proto by itself.

Thoughts?

[zoffixznet]

It defaults to sub, so you can omit it. In core, though, we always add it anyway. Makes it easier to grep 'sub blah' the source.

[Altai-man]

Judging by

> grep -I -r 'multi sub ' doc/ | wc -l
278
> grep -I -r 'multi [^sm]' doc/ | wc -l
50

plain multi case is less common. For the reasons of consistency we can edit such cases to full form. It is quite easy job too, if you have a good editor and some time on board.

[trosel]

I think consistency in the docs is a worthwhile goal

[gfldex]

I do not agree. You don't learn how to deal with complexity by reading code that does it's best to hide it. If we prefer one style we should prefer the shorter version because lazyness is a programmers virtue.

[trosel]

@gfldex Whether the docs show multi sub or just multi, I still think consistency should be the goal.

Programmers can learn complexity by reading real world code / books / tutorials. The docs should feel as if they're all written by one person, no? Hence unifying the comment styles, etc.

[awwaiid]

So how about unifying on multi alone, only using multi sub long-hand when explaining that it is long-hand.

[trosel]

I just read in the docs that one reason why --> is preferred over returns is for consistency in the docs.

So someone at some time deemed consistency in documentation worthwhile. Whoever wrote that 😸

[Altai-man]

@WildYorkies, you can read #1024 (comment) - it explains the choosing of "-->" and there are more reasons: It is more universal(you can use it for constant values) and there are no plans about deprecation, TimToady likes it, etc. The consistency made only one thing in that issue: the issue was opened because of that.

If the docs don't clearly say about possible deprecation and constant values, it is bad. Though, I take a peek now and as for me, it is still explained.

About this issue itself. I'm agreeing with @awwaiid, we can use multi, though it is slightly more work to do.
I don't think that "it is easier to grep" is a nice reason to do otherwise. I mean, why the feature of omitting was added in the first place, if nobody uses it because of greping?

[coke]

What about examples that are contrasting sub vs. method, e.g.:

    multi sub    shift(Array:D )
    multi method shift(Array:D:)

Also, what about 'proto sub'? should we also drop the sub there?

(I can write a test for this, but would like feedback on these items first)

[coke]

WIP on the coke/multi branch

[Altai-man]

@coke, I am working on some new definitions #1494 - here, so, please, ping me somewhere after your work will be finished, so I could follow the changes painlessly.

[Altai-man]

Don't worry, I have already looked into your branch and did appropriate changes.

[rafaelschipiura]

https://github.com/perl6/doc/search?q=%22multi+sub%22

[JJ]

@coke are you still working on this? Should we attempt to merge the branch?

[coke]

Haven't touched it in some time. I think the question from last August is still unanswered.

[JJ]

Also, what about 'proto sub'? should we also drop the sub there?

Yes.

[JJ]

What about examples that are contrasting sub vs. method

In that case it would be better to leave them that way and either whitelist them in the test.

[JJ]

Coming back here, and trying to summarize: a single form, "multi" or "multi sub/method" should be used in the "defined as" part of the docs.
My answer here: in general, we try to use the same form, or as close as possible, as defined in the source. That's the kind of consistency we aim for in the documentation. Since multi sub is preferred in Rakudo, well, we should do the same here. In general, however, creating an issue with 100 (or whatever) tasks is not very actionnable. So the way to solve this is to create, as tagged, an author test that deals with this, and at least fails for pages that are changed.

[JJ]

I'm checking @coke's branch and it seems to be about using multi sub (or multi) everywhere, not only in definitions, which, anyway, are difficult to single out (maybe we should fix that, too). So this is even more difficult to do, and not clear it's really desirable (other than to keep it consistent with source).