Update comment about set_join_pathlist_hook().

The comment introduced by commit e7cb7ee14 was a bit too terse, which
could lead to extensions doing different things within the hook function
than we intend to allow.  Extend the comment to explain what they can do
within the hook function.

Back-patch to all supported branches.

In passing, I rephrased a nearby comment that I recently added to the
back branches.

Reviewed by David Rowley and Andrei Lepikhov.

Discussion: https://postgr.es/m/CAPmGK15SBPA1nr3Aqsdm%2BYyS-ay0Ayo2BRYQ8_A2To9eLqwopQ%40mail.gmail.com

diff --git a/src/backend/optimizer/path/joinpath.c b/src/backend/optimizer/path/joinpath.c
index af240bf27762d0408e4b58b61494a582434148f2..ba702f397668c81bb7d0d491acc8952e5b8f1a5d 100644 (file)
--- a/src/backend/optimizer/path/joinpath.c
+++ b/src/backend/optimizer/path/joinpath.c
@@ -312,7 +312,8 @@ add_paths_to_joinrel(PlannerInfo *root,
        /*
         * createplan.c does not currently support handling of pseudoconstant
         * clauses assigned to joins pushed down by extensions; check if the
-        * restrictlist has such clauses, and if so, disallow pushing down joins.
+        * restrictlist has such clauses, and if not, allow them to consider
+        * pushing down joins.
         */
        if ((joinrel->fdwroutine &&
                 joinrel->fdwroutine->GetForeignJoinPaths) ||
@@ -333,7 +334,10 @@ add_paths_to_joinrel(PlannerInfo *root,
                                                                                                 jointype, &extra);
 
        /*
-        * 6. Finally, give extensions a chance to manipulate the path list.
+        * 6. Finally, give extensions a chance to manipulate the path list.  They
+        * could add new paths (such as CustomPaths) by calling add_path(), or
+        * add_partial_path() if parallel aware.  They could also delete or modify
+        * paths added by the core code.
         */
        if (set_join_pathlist_hook &&
                consider_join_pushdown)