pgsql: Fix misleading comment for get_cheapest_group_keys_order

Fix misleading comment for get_cheapest_group_keys_order

The header comment for get_cheapest_group_keys_order() claimed that the
output arguments were set to a newly allocated list which may be freed by
the calling function, however, this was not always true as the function
would simply leave these arguments untouched in some cases.

This tripped me up when working on 1349d2790 as I mistakenly assumed I
could perform a list_concat with the output parameters. That turned out
bad due to list_concat modifying the original input lists.

In passing, make it more clear that the number of distinct values is
important to reduce tiebreaks during sorts. Also, explain what the
n_preordered parameter means.

Backpatch-through: 15, where get_cheapest_group_keys_order was introduced.

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/55b4966365fa76bda275c409f3aefad43243f12c

Modified Files
--------------
src/backend/optimizer/path/pathkeys.c | 29 ++++++++++++++++-------------
1 file changed, 16 insertions(+), 13 deletions(-)