On 09/11/2018 08:52 AM, Tom Browder wrote:
On Tue, Sep 11, 2018 at 10:39 AM Parrot Raiser <1parr...@gmail.com> wrote:
One of the paradoxes of documentation, and the teaching of many
abstract topics, is that those with the most in-depth knowledge of the
...
I agree with you for the most part. But the docs DO have examples,
and any reader who sees the lack of a suitable one should file an
issue or contribute a suitable change.
I got my start here as a noob p6 user (coming from years of p5 use)
contributing to the docs. And I, too, found many examples too obtuse
for a noob, and have changed some of them.
As experienced as Todd seems to be in p5, he should be able to improve
the docs one way or the other (but get a good book in the meantime;
Andrew Shitov's "Perl 6 at a Glance" is short and sweet for a first
book, Laurent's "Think Perl 6: How to Think Like a Computer Scientist"
for a deeper look).
Cheers,
-Tom
Hi Tom,
There are indeed some examples. They are seldom explained
or even useful. As such are pretty useless. It is my impression
that sometimes the writer is showing off his skills as to how
complicated he can get.
Here is a useless example from contains:
say "Hello, World".contains(',', 1); # OUTPUT: «False»
The "1" is not explained. It took me 20 minutes to figure
out it was the starting position to start looking
in the string. Initially I tough is was an extra command
for case sensitivity, multiple matches, etc..
The docs need to be written in the same fashion as a
spoken language dictionary.
Here is what the word mean
Here is how to use it in sentence.
This is how I would write "contains" in perdoc fashion
(It is posted on issue 2303):
STR contains SUBSTR,POSITION
STR contains SUBSTR
Search for the existence of a SUBSTR in STR starting at
or after POSITION. If POSITION is omitted, starts'
searching from the beginning of the string (0).
If the SUBSTR is located, "contains" returns "True",
otherwise it returns "False".
Examples:
my Str $Haystack = "abc";
my Str $Needle = "c";
my Int $StartIndex = 1; # index to start looking, default = 0
my Bool $Result;
$Result = $Haystack.contains( "c", $StartIndex );
say $Result;'
True
say "abc".contains( "b", 1 ); # start looking at index 1
True
say "abc".contains( "z" ); # start looking at default index 0
False
You walk away knowing exactly how to use the function. And you do not
have to have developer level knowledge to use it!
-T
