Re: boo-boo in run docs?

[email protected] (Peter Pentchev) Fri, 7 Nov 2025 01:01:39 +0200
Newsgroups	perl.perl6.users
Message-ID	<[email protected]>
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

-- 
Peter Pentchev  [email protected] [email protected] [email protected]
PGP key:        https://www.ringlet.net/roam/roam.key.asc
Key fingerprint 2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
signature.asc (application/pgp-signature, 833 B)