Docs: Explain return value from run(), and what happens with $?

[petdance]

The docs don't say what run() returns. It seems to me that:

• run() naturally modifies the value of $? and leaves it as is.
• run()s return value is true if $? is 0, and false if $? is non-zero.
• Nothing in the IPC::Run system explicitly returns $?. If you want to look at it, you just do it yourself.

It would have saved me some time if this was explained in the docs.

I had to go into the IPC::Run code and write some test code examples to figure this out.

[nmisch]

The docs don't say what run() returns. It seems to me that:

• run() naturally modifies the value of $? and leaves it as is.
• run()s return value is true if $? is 0, and false if $? is non-zero.

Section "RETURN VALUES" documents this as:

       run() and finish() return TRUE when all subcommands exit with a 0
       result code.  This is the opposite of perl's system() command.

• Nothing in the IPC::Run system explicitly returns $?.

How do the full_results and full_result methods compare to what you had in mind?

I'm not that great at docs, but I'm happy to review pull requests. I do have my own difficulties finding things in our current perldoc, so it feels far from perfect.

[petdance]

How do the full_results and full_result methods compare to what you had in mind?

So it sounds like if you want $? explicitly you'll have to set up a harness to do it, right?

Maybe what would help (or would have helped me) is if there were a section about run at the beginning, which is the simple way, and which won't give you everything. The part about "run returns true if everything runs OK" is halfway down the doc. I bet that's what most people are looking for. And then, if you want more, like explicitly getting $? or something, then you can set up a harness and here's what that entails.

I'm not that great at docs, but I'm happy to review pull requests.

Let me see what I can pull together that would be a quickstart for people who need more than system() or backticks, but don't want to set up a harness etc, and that would also say "Here's what you can't do with run, but that you can do with a harness."

[nmisch]

Right. That sounds promising.