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.1464386067@sss.pgh.pa.us>

Branch
------
REL9_3_STABLE

Details
-------
http://git.postgresql.org/pg/commitdiff/24c1f64a66d6f7a6448d0c9aedecf3e47a2a0c5e

Modified Files
--------------
src/bin/pg_dump/parallel.c           | 629 ++++++++++++++++++++---------------
src/bin/pg_dump/pg_backup_archiver.c |  12 +-
2 files changed, 361 insertions(+), 280 deletions(-)