pgsql: Lots of comment-fixing, and minor cosmetic cleanup, in pg_dump/p

Lots of comment-fixing, and minor cosmetic cleanup, in pg_dump/parallel.c.

The commentary in this file was in extremely sad shape. The author(s)
had clearly never heard of the project convention that a function header
comment should provide an API spec of some sort for that function. Much
of it was flat out wrong, too --- maybe it was accurate when written, but
if so it had not been updated to track subsequent code revisions. Rewrite
and rearrange to try to bring it up to speed, and annotate some of the
places where more work is needed. (I've refrained from actually fixing
anything of substance ... yet.)

Also, rename a couple of functions for more clarity as to what they do,
do some very minor code rearrangement, remove some pointless Asserts,
fix an incorrect Assert in readMessageFromPipe, and add a missing socket
close in one error exit from pgpipe(). The last would be a bug if we
tried to continue after pgpipe() failure, but since we don't, it's just
cosmetic at present.

Although this is only cosmetic, back-patch to 9.3 where parallel.c was
added. It's sufficiently invasive that it'll pose a hazard for future
back-patching if we don't.

Discussion: <25239(dot)1464386067(at)sss(dot)pgh(dot)pa(dot)us>

Branch
------
master

Details
-------
http://git.postgresql.org/pg/commitdiff/6b3094c26f9ec8688d802e71562e9be714cfe6ac

Modified Files
--------------
src/bin/pg_dump/parallel.c | 620 ++++++++++++++++++++---------------
src/bin/pg_dump/pg_backup_archiver.c | 12 +-
2 files changed, 357 insertions(+), 275 deletions(-)