It's good to have your perspective on how this can be improved, and I'm definitely willing to write more documentation. Any lack in that area is probably due to being too close to the subject area, having spent several years on parallelism in general, and 200+ emails on parallel sequential scan in particular. Your point about the lack of a good header file comment for execParallel.c is a good one, and I'll rectify that next week.
Not on your case in a big way, just noting the need for change there.
I'll help as well, but if you could start with enough basics to allow me to ask questions that will help. Thanks.
--
Simon Riggs http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services