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

On Thu, Feb 26, 2026 at 9:02 PM Ashutosh Bapat
<ashutosh(dot)bapat(dot)oss(at)gmail(dot)com> wrote:
>
> 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.

+1

> > 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.

Thanks for the patch! LGTM.

> 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".

At least for me, the supplementary description that the patch adds
looks sufficient.

Regards,

--
Fujii Masao