Date: Mon, 17 Feb 2025 15:55:50 -0600
From: Nathan Bossart <nathandbossart@gmail.com>
To: Peter Smith <smithpb2250@gmail.com>
Cc: Ilia Evdokimov <ilya.evdokimov@tantorlabs.com>,
	"David G. Johnston" <david.g.johnston@gmail.com>,
	Daniel Gustafsson <daniel@yesql.se>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: describe special values in GUC descriptions more consistently
Message-ID: <Z7OwZv8JuGT6Ytq0@nathan>
References: <Z60M1AmVLCODshn8@nathan>
 <CAHut+PtanfZy6gpRoSBEjsxKRc57v7zoz8oADFHpz_joknYRfA@mail.gmail.com>
 <Z60k4qYL7mtPtB3O@nathan>
 <CAKFQuwbEzaX7Ssw4=ZLkdRG7142MpYNkDGZmMN=RmQXLreB3Tg@mail.gmail.com>
 <Z65vw3mBv8wa7Wfj@nathan>
 <CAKFQuwYx_=44pZ1Pp-3fRFHt36G02Ldq2Db-phtD+EXLJ7VEFA@mail.gmail.com>
 <Z65556VoM7eP-cuc@nathan>
 <Z69zmd7ja4L0Ipo9@nathan>
 <e82d4647-ce7f-45c7-9b01-fb900a050767@tantorlabs.com>
 <CAHut+PtxgXjY+Buz+u4gLHRHZ7SeioEjZx9szgJHfukSK_9wng@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CAHut+PtxgXjY+Buz+u4gLHRHZ7SeioEjZx9szgJHfukSK_9wng@mail.gmail.com>
Archived-At: <https://www.postgresql.org/message-id/Z7OwZv8JuGT6Ytq0%40nathan>
Precedence: bulk

On Tue, Feb 18, 2025 at 08:14:58AM +1100, Peter Smith wrote:
> SUGGESTION
> "-1 disables logging plans. 0 means log all plans."

+1

>   DefineCustomIntVariable("auto_explain.log_parameter_max_length",
>   "Sets the maximum length of query parameters to log.",
> - "Zero logs no query parameters, -1 logs them in full.",
> + "0 logs no query parameters, -1 logs them in full.",
> 
> SUGGESTION #1 (main description part)
> In fact that whole description seems incompatible with the
> documentation. IMO it should be "Sets the maximum length of query
> parameter VALUES to log.".

I'm not sure omitting "values" changes the meaning in any discernible way,
but I'm not opposed to adding it.

> SUGGESTION #2 (special value part)
> "-1 disables logging parameter values."
> OR
> "-1 disables logging parameter values. 0 means log parameter values in full"
> 
> TBH, I am unsure if this one should even mention the value 0 because
> there are already examples of "max" GUCs similar to this that say
> nothing about 0 since the meaning should be clear.
> e.g. log_parameter_max_length doesn't mention 0.
> e.g. log_parameter_max_length_on_error doesn't mention 0.

I think you've got the meanings swapped here.  It should be:

	-1 means log parameter values in full. 0 disables logging parameter values.

But I agree that we can omit the description for 0 here.

-- 
nathan