The signatures in the docs are often the exact same signatures
as the code they are documenting.
> Str.^lookup('contains').candidates.map: *.signature.say
(Str:D: Cool:D $needle, *%_)
(Str:D: Str:D $needle, *%_)
(Str:D: Cool:D $needle, Cool:D $pos, *%_)
(Str:D: Str:D $needle, Int:D $pos, *%_)
So the name of the positional parameters tend to be whatever
the person who wrote the code decided to call them.
If you have a better idea, you could create an issue or pull-request.
---
The real problem is that someone has to be able to see it
from the beginner's perspective, but also has to know how
it actually works.
They also have to have the time and ambition to go through them.
If you create a detailed issue, or pull-request, at least people
will know where their work is needed.
---
There have been cases where documenting something
lead to the discovery of a bug in the implementation.
On Tue, Sep 11, 2018 at 7:05 PM ToddAndMargo <toddandma...@zoho.com> wrote:
>
> On 09/11/2018 08:17 AM, Laurent Rosenfeld via perl6-users wrote:
> > Hi Todd,
> >
> > I fully agree with Tom B.'s message that you should really set out to
> > read a Perl 6 book. Many of the things you asked are covered in most of
> > the available books. And the available books are easier than the
> > official documentation for a beginner to start understand the basic
> > underlying concepts.
> >
> > I should add that you don't even have to /buy/ one book, since my own
> > /Think Perl 6/ book is freely available on the Internet (Creative
> > Commons license): https://greenteapress.com/wp/think-perl-6/. Well, if
> > you are interested in reading it, I'd suggest you look for the PDF on my
> > Github repository
> > (https://github.com/LaurentRosenfeld/thinkperl6/tree/master/PDF),
> > because it is more up-to-date (number of small corrections made
> > following comments from readers).
> >
> > So it would take you just a few minutes (at no cost) to download it and
> > start enjoying it.
> >
> > Cheers,
> > Laurent.
>
>
> Hi Laurent,
>
> Ordinarily I would agree with you. But I know my own brain and
> how it works. I only learn by doing. Have tried to change that
> and can't.
>
> When I "dive in", I open up the reference docs and bang away.
> I also use Google, but that is next to useless in Perl 6 as Perl 5
> hits drowned Perl 6 out.
>
> I am 62 years old, have a bachelors degree in Electronic and
> Computer Engineering, Cum Laude and have been programming
> things all my life. I live with the reference page open
> while pounding out code.
>
> Perl 6's document are next to useless for me. This is the first
> time I have come across references that were so badly done.
> And programming of the Automated Test Equipment I did
> had some documents to behold. CP-M was not fun either.
>
> Do not misunderstand, I ADORE Perl 6. It is a wonderful clean
> up of Perl 5, especially the subroutine definitions and regex's.
> The only step backward is the docs.
>
> The developers have their own specification/documentation.
> The reference docs need to be written for the rest of us.
>
> By the way, I never mastered Perl 5's regex's. I used them,
> but could never figure out exactly what I did. In Perl 6
> I now can throw them together off the top of my head. It
> is kind of fun.
>
> -T
>
> --
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> Computers are like air conditioners.
> They malfunction when you open windows
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
