On Thu, Nov 06, 2025 at 03:34:32PM -0800, ToddAndMargo via perl6-users wrote: > 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.
Maybe exitcode should indeed be added as part of the examples in the `run` documentation, since it is one of the things that are most often used, just like `out` and `err` are. But the `run` documentation cannot reasonably include all of the `Proc` members; the only sensible thing is to refer to `Proc` for everything else. > 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, It is in the definition. It is listed as one of the methods, because that is what it is. "The end of the document" is the section that lists all of the methods that you can call. What you seem to mean is that it is not passed as a parameter to the constructor - it cannot possibly be, because `run` DOESN'T KNOW the exitcode when it starts the program :) The exitcode is obtained later in a way that `Proc` handles internally. The parameters to the constructor are NOT all the properties of an object, and they are not all the *methods* you can call on an object. You don't pass a string's length as a parameter when you create it out of a series of characters; you get the length from a method that you call afterwards, once the string has been built up. Same with the exitcode - it cannot possibly be known when a command is started, so it is not a parameter to `new`; it is obtained later, and you can ask about it by calling the exitcode method. 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
Description: PGP signature
