Further refine patch for commenting operator implementation functions.

Instead of manually maintaining the "implementation of XXX operator"
comments in pg_proc.h, delete all those entries and let initdb create
them via a join.  To let initdb figure out which name to use when there
is a conflict, change the comments for deprecated operators to say they
are deprecated --- which seems like a good thing to do anyway.

src/bin/initdb/initdb.c

@@ -1494,6 +1494,19 @@ setup_description(void)
 				"  FROM tmp_pg_shdescription t, pg_class c "
 				"   WHERE c.relname = t.classname;\n");
 
+	/* Create default descriptions for operator implementation functions */
+	PG_CMD_PUTS("WITH funcdescs AS ( "
+				"SELECT p.oid as p_oid, oprname, "
+				"coalesce(obj_description(o.oid, 'pg_operator'),'') as opdesc "
+				"FROM pg_proc p JOIN pg_operator o ON oprcode = p.oid ) "
+				"INSERT INTO pg_description "
+				"  SELECT p_oid, 'pg_proc'::regclass, 0, "
+				"    'implementation of ' || oprname || ' operator' "
+				"  FROM funcdescs "
+				"  WHERE opdesc NOT LIKE 'deprecated%' AND "
+				"  NOT EXISTS (SELECT 1 FROM pg_description "
+                "    WHERE objoid = p_oid AND classoid = 'pg_proc'::regclass);\n");
+
 	PG_CMD_CLOSE;
 
 	check_ok();

src/include/catalog/catversion.h

@@ -53,6 +53,6 @@
  */
 
 /*							yyyymmddN */
-#define CATALOG_VERSION_NO	201103031
+#define CATALOG_VERSION_NO	201103032
 
 #endif

src/include/catalog/pg_operator.h

@@ -83,6 +83,13 @@ typedef FormData_pg_operator *Form_pg_operator;
  * ----------------
  */
 
+/*
+ * Note: every entry in pg_operator.h is expected to have a DESCR() comment.
+ * If the operator is a deprecated equivalent of some other entry, be sure
+ * to comment it as such so that initdb doesn't think it's a preferred name
+ * for the underlying function.
+ */
+
 DATA(insert OID =  15 ( "="		   PGNSP PGUID b t t	23	20	16 416	36 int48eq eqsel eqjoinsel ));
 DESCR("equal");
 DATA(insert OID =  36 ( "<>"	   PGNSP PGUID b f f	23	20	16 417	15 int48ne neqsel neqjoinsel ));
@@ -141,7 +148,7 @@ DESCR("equal");
 DATA(insert OID = 388 (  "!"	   PGNSP PGUID r f f	20	 0	1700  0  0 numeric_fac - - ));
 DESCR("factorial");
 DATA(insert OID = 389 (  "!!"	   PGNSP PGUID l f f	 0	20	1700  0  0 numeric_fac - - ));
-DESCR("factorial");
+DESCR("deprecated, use ! instead");
 DATA(insert OID = 385 (  "="	   PGNSP PGUID b f t	29	29	16 385	 0 cideq eqsel eqjoinsel ));
 DESCR("equal");
 DATA(insert OID = 386 (  "="	   PGNSP PGUID b f t	22	22	16 386	 0 int2vectoreq eqsel eqjoinsel ));
@@ -641,7 +648,7 @@ DESCR("is above (allows touching)");
 DATA(insert OID =  801 (  "<^"	   PGNSP PGUID b f f	603  603	 16    0  0 box_below_eq positionsel positionjoinsel ));
 DESCR("is below (allows touching)");
 DATA(insert OID =  802 (  "?#"	   PGNSP PGUID b f f	603  603	 16    0  0 box_overlap areasel areajoinsel ));
-DESCR("overlaps");
+DESCR("deprecated, use && instead");
 DATA(insert OID =  803 (  "#"	   PGNSP PGUID b f f	603  603	603    0  0 box_intersect - - ));
 DESCR("box intersection");
 DATA(insert OID =  804 (  "+"	   PGNSP PGUID b f f	603  600	603    0  0 box_add - - ));
@@ -1521,41 +1528,41 @@ DESCR("concatenate");
 
 /* obsolete names for contains/contained-by operators; remove these someday */
 DATA(insert OID = 2860 (  "@"	   PGNSP PGUID b f f 604 604	16 2861  0 poly_contained contsel contjoinsel ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2861 (  "~"	   PGNSP PGUID b f f 604 604	16 2860  0 poly_contain contsel contjoinsel ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2862 (  "@"	   PGNSP PGUID b f f 603 603	16 2863  0 box_contained contsel contjoinsel ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2863 (  "~"	   PGNSP PGUID b f f 603 603	16 2862  0 box_contain contsel contjoinsel ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2864 (  "@"	   PGNSP PGUID b f f 718 718	16 2865  0 circle_contained contsel contjoinsel ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2865 (  "~"	   PGNSP PGUID b f f 718 718	16 2864  0 circle_contain contsel contjoinsel ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2866 (  "@"	   PGNSP PGUID b f f 600 603	16	 0	 0 on_pb - - ));
-DESCR("point inside box");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2867 (  "@"	   PGNSP PGUID b f f 600 602	16 2868  0 on_ppath - - ));
-DESCR("point within closed path, or point on open path");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2868 (  "~"	   PGNSP PGUID b f f 602 600	 16  2867  0 path_contain_pt - - ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2869 (  "@"	   PGNSP PGUID b f f 600 604	 16  2870  0 pt_contained_poly - - ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2870 (  "~"	   PGNSP PGUID b f f 604 600	 16  2869  0 poly_contain_pt - - ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2871 (  "@"	   PGNSP PGUID b f f 600 718	 16  2872  0 pt_contained_circle - - ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2872 (  "~"	   PGNSP PGUID b f f 718 600	 16  2871  0 circle_contain_pt - - ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 DATA(insert OID = 2873 (  "@"	   PGNSP PGUID b f f 600 628 16   0  0 on_pl - - ));
-DESCR("point on line");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2874 (  "@"	   PGNSP PGUID b f f 600 601 16   0  0 on_ps - - ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2875 (  "@"	   PGNSP PGUID b f f 601 628 16   0  0 on_sl - - ));
-DESCR("lseg on line");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2876 (  "@"	   PGNSP PGUID b f f 601 603 16   0  0 on_sb - - ));
-DESCR("is contained by");
+DESCR("deprecated, use <@ instead");
 DATA(insert OID = 2877 (  "~"	   PGNSP PGUID b f f 1034 1033	 16 0 0 aclcontains - - ));
-DESCR("contains");
+DESCR("deprecated, use @> instead");
 
 /* uuid operators */
 DATA(insert OID = 2972 (  "="	   PGNSP PGUID b t t 2950 2950 16 2972 2973 uuid_eq eqsel eqjoinsel ));
@@ -1607,9 +1614,9 @@ DESCR("text search match");
 DATA(insert OID = 3637 (  "@@"	   PGNSP PGUID b f f 3615	 3614	 16 3636	0	 ts_match_qv   tsmatchsel tsmatchjoinsel ));
 DESCR("text search match");
 DATA(insert OID = 3660 (  "@@@"    PGNSP PGUID b f f 3614	 3615	 16 3661	0	 ts_match_vq   tsmatchsel tsmatchjoinsel ));
-DESCR("text search match");
+DESCR("deprecated, use @@ instead");
 DATA(insert OID = 3661 (  "@@@"    PGNSP PGUID b f f 3615	 3614	 16 3660	0	 ts_match_qv   tsmatchsel tsmatchjoinsel ));
-DESCR("text search match");
+DESCR("deprecated, use @@ instead");
 DATA(insert OID = 3674 (  "<"	   PGNSP PGUID b f f 3615	 3615	 16 3679 3678	 tsquery_lt scalarltsel scalarltjoinsel ));
 DESCR("less than");
 DATA(insert OID = 3675 (  "<="	   PGNSP PGUID b f f 3615	 3615	 16 3678 3679	 tsquery_le scalarltsel scalarltjoinsel ));

src/test/regress/expected/opr_sanity.out

@@ -661,37 +661,26 @@ 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 (mostly legacy
--- duplicate names for operators) there are multiple operators referencing
--- the same pg_proc entry, and of course the function comment can only match
--- one of them; so don't print functions for which there's any matching
--- entry.  This still leaves a small number of functions for which the
--- comment is intentionally different because we expect the function to be
--- used on its own as well as via the operator; generally, in these special
--- cases, the function and operator comments should match.
+-- 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.
+-- 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 (
-  SELECT p.oid as p_oid, proname, o.oid::regoperator as operator,
+  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, operator, prodesc, oprdesc FROM funcdescs
+SELECT * FROM funcdescs
   WHERE prodesc IS DISTINCT FROM expecteddesc
-    AND NOT EXISTS (SELECT 1 FROM funcdescs f2
-                    WHERE f2.p_oid = funcdescs.p_oid
-                      AND f2.prodesc = f2.expecteddesc)
-ORDER BY 1,3;
- p_oid |    proname    |        operator         |               prodesc               |               oprdesc               
--------+---------------+-------------------------+-------------------------------------+-------------------------------------
-   378 | array_append  | ||(anyarray,anyelement) | append element onto end of array    | append element onto end of array
-   379 | array_prepend | ||(anyelement,anyarray) | prepend element onto front of array | prepend element onto front of array
-  1035 | aclinsert     | +(aclitem[],aclitem)    | add/update ACL item                 | add/update ACL item
-  1036 | aclremove     | -(aclitem[],aclitem)    | remove ACL item                     | remove ACL item
-  1037 | aclcontains   | @>(aclitem[],aclitem)   | contains                            | contains
-  1037 | aclcontains   | ~(aclitem[],aclitem)    | contains                            | contains
-(6 rows)
+    AND oprdesc NOT LIKE 'deprecated%'
+    AND prodesc IS DISTINCT FROM oprdesc;
+ p_oid | proname | o_oid | prodesc | expecteddesc | oprdesc 
+-------+---------+-------+---------+--------------+---------
+(0 rows)
 
 -- **************** pg_aggregate ****************
 -- Look for illegal values in pg_aggregate fields.

src/test/regress/sql/opr_sanity.sql

@@ -529,28 +529,23 @@ 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 (mostly legacy
--- duplicate names for operators) there are multiple operators referencing
--- the same pg_proc entry, and of course the function comment can only match
--- one of them; so don't print functions for which there's any matching
--- entry.  This still leaves a small number of functions for which the
--- comment is intentionally different because we expect the function to be
--- used on its own as well as via the operator; generally, in these special
--- cases, the function and operator comments should match.
+-- 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.
+-- 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 (
-  SELECT p.oid as p_oid, proname, o.oid::regoperator as operator,
+  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, operator, prodesc, oprdesc FROM funcdescs
+SELECT * FROM funcdescs
   WHERE prodesc IS DISTINCT FROM expecteddesc
-    AND NOT EXISTS (SELECT 1 FROM funcdescs f2
-                    WHERE f2.p_oid = funcdescs.p_oid
-                      AND f2.prodesc = f2.expecteddesc)
-ORDER BY 1,3;
+    AND oprdesc NOT LIKE 'deprecated%'
+    AND prodesc IS DISTINCT FROM oprdesc;
 
 
 -- **************** pg_aggregate ****************