doc: Clarify that empty COMMENT string removes the comment.

Clarify the documentation of COMMENT ON to state that specifying an empty
string is treated as NULL, meaning that the comment is removed.

This makes the behavior explicit and avoids possible confusion about how
empty strings are handled.

Also adds regress test cases that use empty string to remove a comment.

Backpatch to all supported versions.

Author: Chao Li <lic@highgo.com>
Reviewed-by: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Shengbin Zhao <zshengbin91@gmail.com>
Reviewed-by: Jim Jones <jim.jones@uni-muenster.de>
Reviewed-by: zhangqiang <zhang_qiang81@163.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/26476097-B1C1-4BA8-AA92-0AD0B8EC7190@gmail.com
Backpatch-through: 14

diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
index ae4640b623500649dcd49ef8836beb4d0113e024..115889ef58ffbe5dcbc345bc783195b59d15e21f 100644 (file)
--- a/doc/src/sgml/ref/comment.sgml
+++ b/doc/src/sgml/ref/comment.sgml
@@ -80,14 +80,16 @@ COMMENT ON
   <title>Description</title>
 
   <para>
-   <command>COMMENT</command> stores a comment about a database object.
+   <command>COMMENT</command> stores, replaces, or removes the comment on a
+   database object.
   </para>
 
   <para>
-   Only one comment string is stored for each object, so to modify a comment,
-   issue a new <command>COMMENT</command> command for the same object.  To remove a
-   comment, write <literal>NULL</literal> in place of the text string.
-   Comments are automatically dropped when their object is dropped.
+   Only one comment string is stored for each object.  Issuing a new
+   <command>COMMENT</command> command for the same object replaces the
+   existing comment.  Specifying <literal>NULL</literal> or an empty
+   string (<literal>''</literal>) removes the comment.  Comments are
+   automatically dropped when their object is dropped.
   </para>
 
   <para>
@@ -265,7 +267,8 @@ COMMENT ON
     <term><replaceable class="parameter">string_literal</replaceable></term>
     <listitem>
      <para>
-      The new comment contents, written as a string literal.
+      The new comment contents, written as a string literal.  An empty string
+      (<literal>''</literal>) removes the comment.
      </para>
     </listitem>
    </varlistentry>
@@ -274,7 +277,7 @@ COMMENT ON
     <term><literal>NULL</literal></term>
     <listitem>
      <para>
-      Write <literal>NULL</literal> to drop the comment.
+      Write <literal>NULL</literal> to remove the comment.
      </para>
     </listitem>
    </varlistentry>
@@ -361,6 +364,7 @@ COMMENT ON TRANSFORM FOR hstore LANGUAGE plpythonu IS 'Transform between hstore
 COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
 COMMENT ON TYPE complex IS 'Complex number data type';
 COMMENT ON VIEW my_view IS 'View of departmental costs';
+COMMENT ON VIEW my_view IS NULL;
 </programlisting></para>
  </refsect1>
 

diff --git a/src/test/regress/expected/create_index.out b/src/test/regress/expected/create_index.out
index be80774dd4fbe965a6e7a29aec0f8256bd3cb8cd..ad8de5b3a6fa49560ab7564eaa923518bdc12198 100644 (file)
--- a/src/test/regress/expected/create_index.out
+++ b/src/test/regress/expected/create_index.out
@@ -30,6 +30,20 @@ COMMENT ON INDEX six_wrong IS 'bad index';
 ERROR:  relation "six_wrong" does not exist
 COMMENT ON INDEX six IS 'good index';
 COMMENT ON INDEX six IS NULL;
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+ six_comment_is_null 
+---------------------
+ t
+(1 row)
+
+COMMENT ON INDEX six IS 'add the comment back';
+COMMENT ON INDEX six IS ''; -- empty string removes the comment, same as NULL
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+ six_comment_is_null 
+---------------------
+ t
+(1 row)
+
 --
 -- BTREE ascending/descending cases
 --

diff --git a/src/test/regress/sql/create_index.sql b/src/test/regress/sql/create_index.sql
index b4c49405ae21ef2c548d63f59481ee59f0cab562..47d6124aebb241748c03fd360f5e7bbc38abf275 100644 (file)
--- a/src/test/regress/sql/create_index.sql
+++ b/src/test/regress/sql/create_index.sql
@@ -42,6 +42,10 @@ CREATE INDEX six ON shighway USING btree (name text_ops);
 COMMENT ON INDEX six_wrong IS 'bad index';
 COMMENT ON INDEX six IS 'good index';
 COMMENT ON INDEX six IS NULL;
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
+COMMENT ON INDEX six IS 'add the comment back';
+COMMENT ON INDEX six IS ''; -- empty string removes the comment, same as NULL
+SELECT obj_description('six'::regclass, 'pg_class') IS NULL AS six_comment_is_null;
 
 --
 -- BTREE ascending/descending cases