psql: improve description consistency of \dTS data types

This was done particularly for geometric data types.

Reported-by: Christoph Berg

Discussion: https://postgr.es/m/[email protected]

Co-authored-by: Kyotaro Horiguchi

Backpatch-through: master

Author: bmomjian

doc/src/sgml/datatype.sgml

@@ -3366,13 +3366,13 @@ SELECT person.name, holidays.num_weeks FROM person, holidays
         <entry><type>lseg</type></entry>
         <entry>32 bytes</entry>
         <entry>Finite line segment</entry>
-        <entry>((x1,y1),(x2,y2))</entry>
+        <entry>[(x1,y1),(x2,y2)]</entry>
        </row>
        <row>
         <entry><type>box</type></entry>
         <entry>32 bytes</entry>
         <entry>Rectangular box</entry>
-        <entry>((x1,y1),(x2,y2))</entry>
+        <entry>(x1,y1),(x2,y2)</entry>
        </row>
        <row>
         <entry><type>path</type></entry>

src/include/catalog/pg_type.dat

@@ -32,7 +32,7 @@
 # OIDS 1 - 99
 
 { oid => '16', array_type_oid => '1000',
-  descr => 'boolean, \'true\'/\'false\'',
+  descr => 'boolean, format \'t\'/\'f\'',
   typname => 'bool', typlen => '1', typbyval => 't', typcategory => 'B',
   typispreferred => 't', typinput => 'boolin', typoutput => 'boolout',
   typreceive => 'boolrecv', typsend => 'boolsend', typalign => 'c' },
@@ -90,7 +90,7 @@
   typispreferred => 't', typinput => 'oidin', typoutput => 'oidout',
   typreceive => 'oidrecv', typsend => 'oidsend', typalign => 'i' },
 { oid => '27', array_type_oid => '1010',
-  descr => '(block, offset), physical location of tuple',
+  descr => 'tuple physical location, format \'(block,offset)\'',
   typname => 'tid', typlen => '6', typbyval => 'f', typcategory => 'U',
   typinput => 'tidin', typoutput => 'tidout', typreceive => 'tidrecv',
   typsend => 'tidsend', typalign => 's' },
@@ -179,34 +179,34 @@
 # OIDS 600 - 699
 
 { oid => '600', array_type_oid => '1017',
-  descr => 'geometric point \'(x, y)\'',
+  descr => 'geometric point, format \'(x,y)\'',
   typname => 'point', typlen => '16', typbyval => 'f', typcategory => 'G',
   typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
   typinput => 'point_in', typoutput => 'point_out', typreceive => 'point_recv',
   typsend => 'point_send', typalign => 'd' },
 { oid => '601', array_type_oid => '1018',
-  descr => 'geometric line segment \'(pt1,pt2)\'',
+  descr => 'geometric line segment, format \'[point1,point2]\'',
   typname => 'lseg', typlen => '32', typbyval => 'f', typcategory => 'G',
   typsubscript => 'raw_array_subscript_handler', typelem => 'point',
   typinput => 'lseg_in', typoutput => 'lseg_out', typreceive => 'lseg_recv',
   typsend => 'lseg_send', typalign => 'd' },
 { oid => '602', array_type_oid => '1019',
-  descr => 'geometric path \'(pt1,...)\'',
+  descr => 'geometric path, format \'(point1,...)\'',
   typname => 'path', typlen => '-1', typbyval => 'f', typcategory => 'G',
   typinput => 'path_in', typoutput => 'path_out', typreceive => 'path_recv',
   typsend => 'path_send', typalign => 'd', typstorage => 'x' },
 { oid => '603', array_type_oid => '1020',
-  descr => 'geometric box \'(lower left,upper right)\'',
+  descr => 'geometric box, format \'lower left point,upper right point\'',
   typname => 'box', typlen => '32', typbyval => 'f', typcategory => 'G',
   typdelim => ';', typsubscript => 'raw_array_subscript_handler',
   typelem => 'point', typinput => 'box_in', typoutput => 'box_out',
   typreceive => 'box_recv', typsend => 'box_send', typalign => 'd' },
 { oid => '604', array_type_oid => '1027',
-  descr => 'geometric polygon \'(pt1,...)\'',
+  descr => 'geometric polygon, format \'(point1,...)\'',
   typname => 'polygon', typlen => '-1', typbyval => 'f', typcategory => 'G',
   typinput => 'poly_in', typoutput => 'poly_out', typreceive => 'poly_recv',
   typsend => 'poly_send', typalign => 'd', typstorage => 'x' },
-{ oid => '628', array_type_oid => '629', descr => 'geometric line',
+{ oid => '628', array_type_oid => '629', descr => 'geometric line, formats \'{A,B,C}\'/\'[point1,point2]\'',
   typname => 'line', typlen => '24', typbyval => 'f', typcategory => 'G',
   typsubscript => 'raw_array_subscript_handler', typelem => 'float8',
   typinput => 'line_in', typoutput => 'line_out', typreceive => 'line_recv',
@@ -230,7 +230,7 @@
   typcategory => 'X', typinput => 'unknownin', typoutput => 'unknownout',
   typreceive => 'unknownrecv', typsend => 'unknownsend', typalign => 'c' },
 { oid => '718', array_type_oid => '719',
-  descr => 'geometric circle \'(center,radius)\'',
+  descr => 'geometric circle, format \'<center point,radius>\'',
   typname => 'circle', typlen => '24', typbyval => 'f', typcategory => 'G',
   typinput => 'circle_in', typoutput => 'circle_out',
   typreceive => 'circle_recv', typsend => 'circle_send', typalign => 'd' },
@@ -271,14 +271,14 @@
   typinput => 'aclitemin', typoutput => 'aclitemout', typreceive => '-',
   typsend => '-', typalign => 'd' },
 { oid => '1042', array_type_oid => '1014',
-  descr => 'char(length), blank-padded string, fixed storage length',
+  descr => '\'char(length)\' blank-padded string, fixed storage length',
   typname => 'bpchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
   typinput => 'bpcharin', typoutput => 'bpcharout', typreceive => 'bpcharrecv',
   typsend => 'bpcharsend', typmodin => 'bpchartypmodin',
   typmodout => 'bpchartypmodout', typalign => 'i', typstorage => 'x',
   typcollation => 'default' },
 { oid => '1043', array_type_oid => '1015',
-  descr => 'varchar(length), non-blank-padded string, variable storage length',
+  descr => '\'varchar(length)\' non-blank-padded string, variable storage length',
   typname => 'varchar', typlen => '-1', typbyval => 'f', typcategory => 'S',
   typinput => 'varcharin', typoutput => 'varcharout',
   typreceive => 'varcharrecv', typsend => 'varcharsend',
@@ -310,7 +310,7 @@
   typsend => 'timestamptz_send', typmodin => 'timestamptztypmodin',
   typmodout => 'timestamptztypmodout', typalign => 'd' },
 { oid => '1186', array_type_oid => '1187',
-  descr => '@ <number> <units>, time interval',
+  descr => 'time interval, format \'number units ...\'',
   typname => 'interval', typlen => '16', typbyval => 'f', typcategory => 'T',
   typispreferred => 't', typinput => 'interval_in', typoutput => 'interval_out',
   typreceive => 'interval_recv', typsend => 'interval_send',
@@ -345,7 +345,7 @@
 # OIDS 1700 - 1799
 
 { oid => '1700', array_type_oid => '1231',
-  descr => 'numeric(precision, decimal), arbitrary precision number',
+  descr => '\'numeric(precision, scale)\' arbitrary precision number',
   typname => 'numeric', typlen => '-1', typbyval => 'f', typcategory => 'N',
   typinput => 'numeric_in', typoutput => 'numeric_out',
   typreceive => 'numeric_recv', typsend => 'numeric_send',
@@ -400,13 +400,13 @@
   typalign => 'i' },
 
 # uuid
-{ oid => '2950', array_type_oid => '2951', descr => 'UUID datatype',
+{ oid => '2950', array_type_oid => '2951', descr => 'UUID',
   typname => 'uuid', typlen => '16', typbyval => 'f', typcategory => 'U',
   typinput => 'uuid_in', typoutput => 'uuid_out', typreceive => 'uuid_recv',
   typsend => 'uuid_send', typalign => 'c' },
 
 # pg_lsn
-{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN datatype',
+{ oid => '3220', array_type_oid => '3221', descr => 'PostgreSQL LSN',
   typname => 'pg_lsn', typlen => '8', typbyval => 'FLOAT8PASSBYVAL',
   typcategory => 'U', typinput => 'pg_lsn_in', typoutput => 'pg_lsn_out',
   typreceive => 'pg_lsn_recv', typsend => 'pg_lsn_send', typalign => 'd' },
@@ -452,12 +452,12 @@
   typreceive => 'jsonpath_recv', typsend => 'jsonpath_send', typalign => 'i',
   typstorage => 'x' },
 
-{ oid => '2970', array_type_oid => '2949', descr => 'txid snapshot',
+{ oid => '2970', array_type_oid => '2949', descr => 'transaction snapshot',
   typname => 'txid_snapshot', typlen => '-1', typbyval => 'f',
   typcategory => 'U', typinput => 'txid_snapshot_in',
   typoutput => 'txid_snapshot_out', typreceive => 'txid_snapshot_recv',
   typsend => 'txid_snapshot_send', typalign => 'd', typstorage => 'x' },
-{ oid => '5038', array_type_oid => '5039', descr => 'snapshot',
+{ oid => '5038', array_type_oid => '5039', descr => 'transaction snapshot',
   typname => 'pg_snapshot', typlen => '-1', typbyval => 'f', typcategory => 'U',
   typinput => 'pg_snapshot_in', typoutput => 'pg_snapshot_out',
   typreceive => 'pg_snapshot_recv', typsend => 'pg_snapshot_send',
@@ -633,7 +633,9 @@
   typoutput => 'tsm_handler_out', typreceive => '-', typsend => '-',
   typalign => 'i' },
 { oid => '269',
-  typname => 'table_am_handler', typlen => '4', typbyval => 't', typtype => 'p',
+  typname => 'table_am_handler',
+  descr => 'pseudo-type for the result of a table AM handler function',
+  typlen => '4', typbyval => 't', typtype => 'p',
   typcategory => 'P', typinput => 'table_am_handler_in',
   typoutput => 'table_am_handler_out', typreceive => '-', typsend => '-',
   typalign => 'i' },
@@ -679,13 +681,13 @@
   typtype => 'p', typcategory => 'P', typinput => 'anycompatiblemultirange_in',
   typoutput => 'anycompatiblemultirange_out', typreceive => '-', typsend => '-',
   typalign => 'd', typstorage => 'x' },
-{ oid => '4600', descr => 'BRIN bloom summary',
+{ oid => '4600', descr => 'pseudo-type representing BRIN bloom summary',
   typname => 'pg_brin_bloom_summary', typlen => '-1', typbyval => 'f',
   typcategory => 'Z', typinput => 'brin_bloom_summary_in',
   typoutput => 'brin_bloom_summary_out',
   typreceive => 'brin_bloom_summary_recv', typsend => 'brin_bloom_summary_send',
   typalign => 'i', typstorage => 'x', typcollation => 'default' },
-{ oid => '4601', descr => 'BRIN minmax-multi summary',
+{ oid => '4601', descr => 'pseudo-type representing BRIN minmax-multi summary',
   typname => 'pg_brin_minmax_multi_summary', typlen => '-1', typbyval => 'f',
   typcategory => 'Z', typinput => 'brin_minmax_multi_summary_in',
   typoutput => 'brin_minmax_multi_summary_out',