Backport upstream comment updates

commit 96f990e2
Author: Tom Lane <tgl@sss.pgh.pa.us>
Date:   Wed Jul 13 20:23:09 2011 -0400

    Update some comments to clarify who does what in targetlist creation.

    No code changes; just avoid blaming query_planner for things it doesn't
    really do.

src/backend/optimizer/plan/planner.c

@@ -1740,17 +1740,17 @@ grouping_planner(PlannerInfo *root, double tuple_fraction)
 				need_sort_for_grouping = true;
 
 				/*
-				 * Always override query_planner's tlist, so that we don't
+				 * Always override create_plan's tlist, so that we don't
 				 * sort useless data from a "physical" tlist.
 				 */
 				need_tlist_eval = true;
 			}
 
 			/*
-			 * create_plan() returns a plan with just a "flat" tlist of
+			 * create_plan returns a plan with just a "flat" tlist of
 			 * required Vars.  Usually we need to insert the sub_tlist as the
 			 * tlist of the top plan node.	However, we can skip that if we
-			 * determined that whatever query_planner chose to return will be
+			 * determined that whatever create_plan chose to return will be
 			 * good enough.
 			 */
 			if (need_tlist_eval)
@@ -1789,7 +1789,7 @@ grouping_planner(PlannerInfo *root, double tuple_fraction)
 			else
 			{
 				/*
-				 * Since we're using query_planner's tlist and not the one
+				 * Since we're using create_plan's tlist and not the one
 				 * make_subplanTargetList calculated, we have to refigure any
 				 * grouping-column indexes make_subplanTargetList computed.
 				 */
@@ -3443,10 +3443,11 @@ choose_hashed_distinct(PlannerInfo *root,
  * make_subplanTargetList
  *	  Generate appropriate target list when grouping is required.
  *
- * When grouping_planner inserts Aggregate, Group, or Result plan nodes
- * above the result of query_planner, we typically want to pass a different
- * target list to query_planner than the outer plan nodes should have.
- * This routine generates the correct target list for the subplan.
+ * When grouping_planner inserts grouping or aggregation plan nodes
+ * above the scan/join plan constructed by query_planner+create_plan,
+ * we typically want the scan/join plan to emit a different target list
+ * than the outer plan nodes should have.  This routine generates the
+ * correct target list for the scan/join subplan.
  *
  * The initial target list passed from the parser already contains entries
  * for all ORDER BY and GROUP BY expressions, but it will not have entries
@@ -3469,17 +3470,20 @@ choose_hashed_distinct(PlannerInfo *root,
  * If we are grouping or aggregating, *and* there are no non-Var grouping
  * expressions, then the returned tlist is effectively dummy; we do not
  * need to force it to be evaluated, because all the Vars it contains
- * should be present in the output of query_planner anyway.
+ * should be present in the "flat" tlist generated by create_plan, though
+ * possibly in a different order.  In that case we'll use create_plan's tlist,
+ * and the tlist made here is only needed as input to query_planner to tell
+ * it which Vars are needed in the output of the scan/join plan.
  *
  * 'tlist' is the query's target list.
  * 'groupColIdx' receives an array of column numbers for the GROUP BY
- *			expressions (if there are any) in the subplan's target list.
+ *			expressions (if there are any) in the returned target list.
  * 'groupOperators' receives an array of equality operators corresponding
  *			the GROUP BY expressions.
  * 'need_tlist_eval' is set true if we really need to evaluate the
- *			result tlist.
+ *			returned tlist as-is.
  *
- * The result is the targetlist to be passed to the subplan.
+ * The result is the targetlist to be passed to query_planner.
  *---------------
  */
 static List *
@@ -3631,7 +3635,7 @@ make_subplanTargetList(PlannerInfo *root,
 
 /*
  * locate_grouping_columns
- *		Locate grouping columns in the tlist chosen by query_planner.
+ *		Locate grouping columns in the tlist chosen by create_plan.
  *
  * This is only needed if we don't use the sub_tlist chosen by
  * make_subplanTargetList.	We have to forget the column indexes found