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

On Thu, Feb 26, 2026 at 11:37 AM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)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