From: Tom Lane <tgl@sss.pgh.pa.us>
To: =?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org>
cc: pgsql-hackers@postgresql.org
Subject: Re: Clarify deleting comments and security labels in synopsis
In-reply-to: <87sffqk4zp.fsf@wibble.ilmari.org>
References: <87sffqk4zp.fsf@wibble.ilmari.org>
Comments: In-reply-to =?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?=
 <ilmari@ilmari.org>
	message dated "Tue, 31 Jan 2023 17:07:06 +0000"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <1139369.1675186526.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Tue, 31 Jan 2023 12:35:26 -0500
Message-ID: <1139370.1675186526@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/1139370.1675186526%40sss.pgh.pa.us>
Precedence: bulk

=?utf-8?Q?Dagfinn_Ilmari_Manns=C3=A5ker?= <ilmari@ilmari.org> writes:
> A user on IRC was confused about how to delete a security label using
> the `SECURITY LABLEL ON … IS …` command, and looking at the docs I can
> see why.

> The synopsis just says `IS 'label'`, which implies that it can only be a
> string. It's not until you read the description for `label` that you
> see "or `NULL` to drop the security label."  I propose making the
> synopsis say `IS { 'label' | NULL }` to make it clear that it can be
> NULL as well.  The same applies to `COMMENT ON … IS …`, which I've also
> changed similarly in the attached.

Agreed; as-is, the syntax summary is not just confusing but outright
wrong.

I think we could go further and split the entry under Parameters
to match:

	'text'
		The new comment (must be a simple string literal,
		not an expression).

	NULL
		Write NULL to drop the comment.


			regards, tom lane