> On Feb 26, 2026, at 23:56, David G. Johnston <[email protected]> > wrote: > > On Thu, Feb 26, 2026 at 5:02 AM Ashutosh Bapat <[email protected]> > 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/
v2-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch
Description: Binary data
