Add comments regarding Exec stream redirection in Pipeline context

[rockbmb]

Esteemed maintainer(s): I submit this PR after having run into the described problem while using this crate.
Hopefully, you will also find it useful enough to be merged.

Issue

If the first or/and last Exec of a Pipeline has had their standard streams redirected, executing the pipeline will cause a runtime panic.

Changes

This PR documents this caveat in the Exec and Pipeline structs, and adds two doctests in Pipeline::join() demonstrating the panic.

[hniksic]

Hi, thanks for working on this, it's really useful to document these panics. Maybe I'd opt for a shorter documentation, though, without the examples.

It might be even better to move the panic to functions that create or modify the pipeline, such as Pipeline::from_exec_iter. That way the issue would be detected earlier, in a more logical place for it to fail, and we could document the panic there.

[rockbmb]

@hniksic thanks for having a look!
I can certainly perform those changes, when I'm done I'll ping again for comment.

[rockbmb]

@hniksic Hello,
Apologies for the delay; new job.

I have a question:

It might be even better to move the panic to functions that create or modify the pipeline

Does that mean we remove the panic from the impl Exec functions?
IMO it should be left there too, because some users may just be joining Execs and not Pipelines; the panic removal would unexpectedly allow improper behavior for them.

[hniksic]

You're right of course, good catch!