Add another regression test cross-checking operator and function comments.

Add a query that lists all the functions that are operator implementation
functions and have a SQL comment that doesn't just say "implementation of
XYZ operator".  (Note that the preceding test checks that such functions'
comments exactly match the corresponding operators' comments.)

While it's not forbidden to add more functions to this list, that should
only be done when we're encouraging users to use either the function or
operator syntax for the functionality, which is a fairly rare situation.

Author: tglsfdc

src/test/regress/expected/opr_sanity.out

@@ -679,9 +679,11 @@ WHERE d.classoid IS NULL AND p1.oid <= 9999;
 (0 rows)
 
 -- Check that operators' underlying functions have suitable comments,
--- namely 'implementation of XXX operator'.  In some cases involving legacy
--- names for operators, there are multiple operators referencing the same
--- pg_proc entry, so ignore operators whose comments say they are deprecated.
+-- namely 'implementation of XXX operator'.  (Note: it's not necessary to
+-- put such comments into pg_proc.h; initdb will generate them as needed.)
+-- In some cases involving legacy names for operators, there are multiple
+-- operators referencing the same pg_proc entry, so ignore operators whose
+-- comments say they are deprecated.
 -- We also have a few functions that are both operator support and meant to
 -- be called directly; those should have comments matching their operator.
 WITH funcdescs AS (
@@ -700,6 +702,31 @@ SELECT * FROM funcdescs
 -------+---------+-------+---------+--------------+---------
 (0 rows)
 
+-- Show all the operator-implementation functions that have their own
+-- comments.  This should happen only in cases where the function and
+-- operator syntaxes are both documented at the user level.
+-- This should be a pretty short list; it's mostly legacy cases.
+WITH funcdescs AS (
+  SELECT p.oid as p_oid, proname, o.oid as o_oid,
+    obj_description(p.oid, 'pg_proc') as prodesc,
+    'implementation of ' || oprname || ' operator' as expecteddesc,
+    obj_description(o.oid, 'pg_operator') as oprdesc
+  FROM pg_proc p JOIN pg_operator o ON oprcode = p.oid
+  WHERE o.oid <= 9999
+)
+SELECT p_oid, proname, prodesc FROM funcdescs
+  WHERE prodesc IS DISTINCT FROM expecteddesc
+    AND oprdesc NOT LIKE 'deprecated%'
+ORDER BY 1;
+ p_oid |    proname    |               prodesc               
+-------+---------------+-------------------------------------
+   378 | array_append  | append element onto end of array
+   379 | array_prepend | prepend element onto front of array
+  1035 | aclinsert     | add/update ACL item
+  1036 | aclremove     | remove ACL item
+  1037 | aclcontains   | contains
+(5 rows)
+
 -- **************** pg_aggregate ****************
 -- Look for illegal values in pg_aggregate fields.
 SELECT ctid, aggfnoid::oid

src/test/regress/sql/opr_sanity.sql

@@ -544,9 +544,11 @@ FROM pg_operator as p1 LEFT JOIN pg_description as d
 WHERE d.classoid IS NULL AND p1.oid <= 9999;
 
 -- Check that operators' underlying functions have suitable comments,
--- namely 'implementation of XXX operator'.  In some cases involving legacy
--- names for operators, there are multiple operators referencing the same
--- pg_proc entry, so ignore operators whose comments say they are deprecated.
+-- namely 'implementation of XXX operator'.  (Note: it's not necessary to
+-- put such comments into pg_proc.h; initdb will generate them as needed.)
+-- In some cases involving legacy names for operators, there are multiple
+-- operators referencing the same pg_proc entry, so ignore operators whose
+-- comments say they are deprecated.
 -- We also have a few functions that are both operator support and meant to
 -- be called directly; those should have comments matching their operator.
 WITH funcdescs AS (
@@ -562,6 +564,23 @@ SELECT * FROM funcdescs
     AND oprdesc NOT LIKE 'deprecated%'
     AND prodesc IS DISTINCT FROM oprdesc;
 
+-- Show all the operator-implementation functions that have their own
+-- comments.  This should happen only in cases where the function and
+-- operator syntaxes are both documented at the user level.
+-- This should be a pretty short list; it's mostly legacy cases.
+WITH funcdescs AS (
+  SELECT p.oid as p_oid, proname, o.oid as o_oid,
+    obj_description(p.oid, 'pg_proc') as prodesc,
+    'implementation of ' || oprname || ' operator' as expecteddesc,
+    obj_description(o.oid, 'pg_operator') as oprdesc
+  FROM pg_proc p JOIN pg_operator o ON oprcode = p.oid
+  WHERE o.oid <= 9999
+)
+SELECT p_oid, proname, prodesc FROM funcdescs
+  WHERE prodesc IS DISTINCT FROM expecteddesc
+    AND oprdesc NOT LIKE 'deprecated%'
+ORDER BY 1;
+
 
 -- **************** pg_aggregate ****************