> On Feb 28, 2026, at 00:44, David G. Johnston <[email protected]> > wrote: > > <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. > + comment, use <literal>NULL</literal> or an empty string > (<literal>''</literal>). > Comments are automatically dropped when their object is dropped. > </para> > > I can live with this but am not a fan. I'd like you to point out other > examples in the documentation references where we use this style of > communication in the description (i.e., telling the user directly what they > should be doing, as opposed to explaining how certain commands and values are > interpreted). I've looked at Grant, Reindex, Vacuum, Update, and Execute: > they are all descriptive, not proscriptive, in tone. We should take this > opportunity to make this page conform to the standard established elsewhere. > I'm not seeing any particular virtue to leaving this page unique in that > regard. And mention above a reason not to. >
I understand your point. To be honest, as a non-native English speaker, I’m not very sensitive to tone, and I didn’t consider the stylistic aspect when I made the change. Based on your suggestion, I’ve rewritten the paragraph to use a descriptive tone: ``` <para> Only one comment string is stored for each object. Issuing a new <command>COMMENT</command> command for the same object replaces the existing comment. Specifying <literal>NULL</literal> or an empty string (<literal>''</literal>) removes the comment. Comments are automatically dropped when their object is dropped. </para> ``` Does this look better? > From: Fujii Masao <[email protected]> > > Besides updating the documentation, isn't it better to also add a regression > test to check that COMMENT with an empty string behaves as expected? Fair point. I searched through the regression tests and noticed that COMMENT ON tests are spread across different object-specific test files. I was hesitant to add empty-string cases everywhere, so for now I added a test case in create_view.sql to verify that IS ‘' removes the comment as expected. If you think it would be better to add an IS '' test wherever IS NULL appears, I’m happy to expand the coverage. Please let me know your preference. PFA v3. Best regards, -- Chao Li (Evan) HighGo Software Co., Ltd. https://www.highgo.com/
v3-0001-doc-Clarify-that-empty-COMMENT-string-removes-the.patch
Description: Binary data
