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 }
<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>
<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>
@@ -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.
The command Description should cover this if we are going to mention it in
the Parameters section. Otherwise a lone comment in the Notes section
would be better IMO. A lone mention in Parameters for string_literal is
unlikely to be noticed - people aren't questioning how string_literal
behaves here and then go look at its description.
On the last point, I choose to show the literal '' value as an explicit
syntax option to point out immediately that writing it as the
string_literal invokes special consideration.
I do think the rewording of the Description paragraphs nicely adds the new
information about the empty string while making the whole thing more
concise with no loss of content. "the comment" is more precise than "a
comment", as are the effects of executing the command.
David J.
