std.process documentation really needs work

[dlangBugzillaToGithub]

Manu reported this on 2020-02-17T06:18:53Z

Transferred from https://issues.dlang.org/show_bug.cgi?id=20584

Description

I have spent about an hour reading the std.process documentation and messing around, but I can't make heads or tails of it.

I'm trying to work out how to spawn a process and manage the input/output streams.
There appear to be functions that are made for this, but the docs are confusing and examples are not helpful.

Consider `executeShell`, it returns `auto`, which appears to be an object, but who knows what members it has? It has at least `status` and `output`... but how do I get the stderr stream which it says it also captures?

I don't think any function in the std lib should ever return `auto`, it's hostile to documentation.

Looking at the source code, it's not easy to follow at all.

pipeProcess, which looks like it might help me, another `auto` result, and the examples are weird; it looks like it waits for the program to finish on scope exit, but it scrapes the stdout and stderr streams while the program is still running (and may not be finished?)

I am getting almost no value out of anything in this whole doco. Someone should consider it from a what-a-user-wants-to-achieve point of view, make useful examples, and get rid of the `auto`s in the api.

I should have spent seconds on this task, but I've been staring at it for hours, and it's still not clear what I'm supposed to do.