Re: boo-boo in run docs?

On 11/6/25 3:01 PM, Peter Pentchev wrote:
> On Thu, Nov 06, 2025 at 12:25:11PM -0800, ToddAndMargo via perl6-users wrote:
>> On 11/6/25 8:18 AM, Peter Pentchev wrote:
>>> On Thu, Nov 06, 2025 at 06:16:28PM +0200, Peter Pentchev wrote:
>>>> On Thu, Nov 06, 2025 at 02:27:43AM -0800, ToddAndMargo via perl6-users wrote:
>>>>> On 11/6/25 1:57 AM, Peter Pentchev wrote:
>>>>>> It doesn't need to be; the documentation of `run` already points to
>>>>>> the documentation of `Proc`, as you point out.
>>>>>
>>>>> In that case, "run's" documentation should have ended at
>>>>> the Proc link.  None of the examples should have been
>>>>> included.  No need for further discussion.
>>>>
>>>> That is not true, since the examples document how one can use `run`
>>>> to start a program; the fact that the returned value is a `Proc`
>>>> object does not matter. The documentation for `run` documents how
>>>> you use `run`; the documentation for `shell` documents how you
>>>> use `shell`. In both cases, they refer to the documentation for `Proc`
>>>> so that they don't have to repeat what is already written there.
>>>
>>> ...and, perhaps even more importantly, so that the documentation for
>>> either `run` or `shell` does not need to be changed if something
>>> changes in `Proc`.
>>
>> Agreed
>>
>>>
>>> G'luck,
>>> Peter
>>>
>>
>> So why put any examples in shell and run?  Just refer to
>> Proc.
> 
> Proc is what many functions could return, and Proc is what some
> functions may even take as an argument. The documentation of Proc
> only describes Proc itself; it should not (mainly because it cannot
> possibly) describe everything that uses it :)
> 
> I mean, do you think the documentation of Int should describe each and
> every function that may ever return an Int? Do you think you should
> look for Proc.exitcode in the documentation of Int?
> 
> G'luck,
> Peter
> 


No. But I do believe that the documentation for run should
include what you need to use the function and not send you
on a wild goose chase to try and figure it out.   exitcode
should have been included in the examples in run's documentation.
And exit code should have been included in the definition of
Proc, not buried at the end of the document,

And the examples that do exist should have been written
with simple code, not fancy code to confuse those with
lesser skills.  In other words, no bragging and showing
off in the examples.

I should also not have had pepper the kinds folks here with
questions on run and forced to write my own documentation.

To me, as a beginner (with Raku), the documentation is
difficult to use as it is clearly written as a refresher
for those that already know what they are doing and not
for novices trying to learn the code.

I wish Raku would take a page from Perl5's documentation,
which is very easy for a beginner to pick up.  They
start with simple examples, explain everything thing involved,
then work up to the fancy stuff.   (Raku is a great clean
up of Perl 5, except for the documentation.)