[Issue 20584] New: std.process documentation really needs work

[d-bugmail at puremagic.com]

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

          Issue ID: 20584
           Summary: std.process documentation really needs work
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: turkeyman at gmail.com

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.

--