Re: describe special values in GUC descriptions more consistently

On Sat, Feb 8, 2025 at 9:27 AM Nathan Bossart <nathandbossart(at)gmail(dot)com> wrote:
>
> For many GUCs, special values like -1, "", etc. have some sort of special
> meaning, such as disabling the feature. While the documentation seems to
> be reasonably good about listing special values, the GUC descriptions are
> less consistent. Many GUC descriptions don't state the special values at
> all, and the ones that do are inconsistent in phrasing and placement (e.g.,
> a couple list them in the short description, but most list them in the long
> description). I figured I'd try to add some consistency here.
>
> In the attached patch, I've attempted to apply the following proposed rules
> to the descriptions of GUCs that accept special values:
>
> * The special values should be listed at the end of the long description.
> * Descriptions should use numerals (0) instead of words (zero).
> * The special value notes should be consistently worded and as direct as
> possible (e.g., "0 disables the timeout.", "An empty string means to use
> the system setting.").
>
> There are a few exceptions, such as max_pred_locks_per_relation and
> search_path, where the special values are too complicated to include. And
> there are cases like unix_socket_directories, listen_addresses,
> application_name, and cluster_name, where the meaning of "" is arguably too
> obvious to bother including. There's a good chance that I've missed a
> couple, too.
>
> Thoughts?
>

+1 for improving consistency.

======

Some patch observations and nits.

1. IMO all places wording as "XXX means to YYY" should be just "XXX
means YYY" (e.g. remove the "to")

e.g. "-1 means to wait forever." => "-1 means wait forever."
e.g. ""-1 means to log values in full." => "-1 means log values in full."

~~~

2. GUC names in messages should always be double quoted.

~~~

3. Wording for the automatic selections.

Some of the special values get calculated and assigned *automatically*
on your behalf. The patch currently seems to be using "means to use"
for these:

I felt all these should be written as:
"XXX means to use YYY" => "XXX means YYY is used."

e.g. "0 means to use a suitable default value." => "0 means a suitable
default value is used."
e.g. "0 means to use a fraction of \"shared_buffers\"." => "0 means a
fraction of \"shared_buffers\" is used".
e.g. "-1 means to use vacuum_cost_limit" => "-1 means
\"vacuum_cost_limit\" is used."

~~

4. When there are multiple special values, it seems more natural if
the values are ordered. Maybe just personal preference.

e.g. "0 means to log all files. -1 disables temporary file logs." =>
"-1 disables temporary file logs. 0 means log all files."

======
Kind Regards,
Peter Smith.
Fujitsu Australia.