Re: doc: Clarify that empty COMMENT string removes the comment

> On Feb 26, 2026, at 23:56, David G. Johnston <david.g.johnston@gmail.com> wrote:
> 
> On Thu, Feb 26, 2026 at 5:02 AM Ashutosh Bapat <ashutosh.bapat.oss@gmail.com> wrote:
> At the beginning of this synopsis there's following sentence. I think
> we need to update it too.
> To remove a
>    comment, write <literal>NULL</literal> in place of the text string.
> 
> 
> I concur this should be a bit less surgical than what is presently proposed.  I would do the following:
> 
> diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml
> index 8d81244910b..45d39e1fc45 100644
> --- a/doc/src/sgml/ref/comment.sgml
> +++ b/doc/src/sgml/ref/comment.sgml
> @@ -66,7 +66,7 @@ COMMENT ON
>    TRIGGER <replaceable class="parameter">trigger_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> |
>    TYPE <replaceable class="parameter">object_name</replaceable> |
>    VIEW <replaceable class="parameter">object_name</replaceable>
> -} IS { <replaceable class="parameter">string_literal</replaceable> | NULL }
> +} IS { <replaceable class="parameter">string_literal</replaceable> | '' | NULL }

I don’t think this is necessary, as I guess we don’t want to encourage the usage of empty string, NULL is clearer.

>  
>  <phrase>where <replaceable>aggregate_signature</replaceable> is:</phrase>
>  
> @@ -80,13 +80,12 @@ 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 for a database object.
>    </para>
>  

I like this. Truly, the command not only adds a new comment, but also update/remove an existing comment.

>    <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.
> +   Each object may have one comment, which will be nonempty.  Setting the
> +   comment to an empty string or <literal>NULL</literal> drops the comment.
>     Comments are automatically dropped when their object is dropped.
>    </para>

I didn’t completely take your wording, but I added “empty string” in this paragraph.

>  
> @@ -266,7 +265,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
> +      drops the comment.
>       </para>
>      </listitem>
>     </varlistentry>
> 
> I don't see a strong need to mention NULL in the description for string_literal; just say what specifying an empty string does directly.
> 

Agreed.

Thanks all for your review. Please see the attached v2.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/