Ok Todd, let me have a go at this issue.
From what I understand, you see 'multi' and think 'there are more than
one', which leads to the question 'where are they?'
My understanding of 'multi' is 'there COULD be more than one', which
leads to the question 'are there any?'
This is actually a very powerful aspect of Raku.
There are (as has been stated in this thread) four types of which multi
= 'could be more than one' and only = 'only one' .
If the developer wrote 'only sub' then, no one else could write a sub
with that name. For a developer of a program or a module, that might be
OK, because it's unlikely anyone else would need/want to use that name.
But for a compiler, the probability is reversed. Someone will want to
use it. That is why in many other languages there are 'reserved words'
which you are not allowed to use.
In Raku, if you develop a new type, for example say a quodion, and you
want to 'add' quodions, then you CAN use + because it can be overloaded.
It is defined as a multi.
Or in your most overused example 'needle' can be rewritten to take a
quodion, which may yield a spectrum of results because that's what
quodions are for.
Since needle is defined as a 'multi', if you write a 'needle' method for
quodions, the needle for strings STILL exists, and Raku will correctly
call the method you wrote for quodions if a quodion is implied, but call
the default needle if a string (or any other type) is used.
Since you have developed the quodion method entirely for your paid
subscribers, the module is NOT available to the public, so you wont tell
anyone about it. So it doesn't have to be in the documentation.
Is this making any sense to you?
Richard
On 08/06/2020 09:25, Peter Pentchev wrote:
On Mon, Jun 08, 2020 at 12:12:07AM -0700, ToddAndMargo via perl6-users wrote:
On 2020-06-07 22:39, Peter Pentchev wrote:
I thought I explained that. The Rakudo developers are*never* finished
with the development of some methods. Somebody*will* want to extend
them in their own module. The Rakudo developers*want* to declare some
methods as "multi" to allow the Rakudo users to write Raku programs that
extend some existing classes to make them do interesting things.
You did and I understood it. Your explanation was well
though out/
What you missed was my point that the developers have a
process for checking in new code. Part of that process
is updating the documentation. That is the proper
time for documentation to be updated. The purpose of
the documentation is not to keep places open for unicorns.
Now you are absolutely correct that the software is NEVER finished. But
Raku is not a "daily" release to the public.
They exist, but are not released to the general public.
Raku has releases. When the new release his, the
documentation need to match the release. It is
all part of the check in process.
Nothing. Needs. To be. Updated.
For the last time. The methods are "multi" for two reasons:
- to allow other parts of Rakudo to use them *internally*
- to allow *module authors* and *application writers* like you and me
to extend them in our own classes
Both of these are very valid reasons to declare some methods as "multi".
Nothing needs to change in the documentation.
What did you learn from going to Github? That you may call
.starts-with() without the :i or :m parameters? Was that not written in
the documentation? Or that you may call .starts-with() with a $needle
being Cool and not Str? Again, was that not written in the
documentation? So what did you learn from going to Github that was not
in the documentation?
Nothing I remember. But that was not my point.
What is your point then? What *exactly* is lacking in the documetation
of the Str.starts-with() method, *and why*? Examples, please.
And no, *don't* say "the internal method without the :i and :m" without
explaining *why* you want it to be "documented".
G'luck,
Peter
