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

On Thu, Feb 26, 2026 at 11:37 AM Chao Li <li.evan.chao@gmail.com> wrote:
>
> Hi,
>
> While reviewing patch [1] before the holiday vacation, I noticed that the COMMENT ON command treats an empty string as NULL, which effectively removes the comment from the object. Today I also saw discussion [2], which mentioned the same problem.
>
> From the code, it seems the behavior is intentional:
> ```
>     /* Reduce empty-string to NULL case */
>     if (comment != NULL && strlen(comment) == 0)
>         comment = NULL;
> ```

This code goes all the way back to
577e21b34f8629ce76651a6388298891f81be99a. So there's no point in
changing it now. Doc update is better.

>
> However, the documentation does not explain this behavior. It currently only says:
> ```
> string_literal
>    The new comment contents, written as a string literal.
> ```
>
> Is it a common pattern that an empty string is treated as NULL, so that the documentation does not need to mention it explicitly? I don’t think so. For example, a similar command, SECURITY LABEL ON, treats an empty string as just an empty string.
>
> This tiny patch enhances the documentation of COMMENT ON to clarify that an empty string is treated as NULL.


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.

For the sake of consistency, I would word the sentence "An empty ... "
to read more like NULL i.e. "Write an empty string to drop the
comment".

-- 
Best Wishes,
Ashutosh Bapat