Subject: Better visualization of default values

From: Marcos Pegoraro <[email-masked]>
Date: Wed, 5 Feb 2025 18:07:13 -0300

Reading DOCs sometimes is boring because you want to know only the default
value of something. I know what that GUC is, I know how to change it, I
only don't remember what its default value is. Then you have to read that
entire paragraph just to read that the default value is ...

So, what you think about this.
It's not complete but you can see if it's useful or not

regards
Marcos

---

From: Peter Smith <[email-masked]>
Date: Thu, 6 Feb 2025 10:58:54 +1100

On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <[email-masked]> wrote:
>
> Reading DOCs sometimes is boring because you want to know only the default value of something. I know what that GUC is, I know how to change it, I only don't remember what its default value is. Then you have to read that entire paragraph just to read that the default value is ...
>

+0.5

IIUC the problem here (if there is one), is just that the default is
sometimes buried within the GUC description.

But just putting the default value adjacent to the GUC name might not
be the best solution because often defaults have special meanings.
e.g. there is no point knowing the default value is -1 unless you know
what that value means. So with your patch, not only is the default
value duplicated, but you are back where you started having to read
all the description text again to learn what it means.

IMO it would be better simply to ensure that defaults are always
described in a consistent place within all GUC descriptions, Then they
are easy to find because you always know where to look for them. In
other words, add nothing new -- just slightly rearrange and/or add
blank lines to the existing text.

Like this:

<guc-name> (type)
    <one line terse description>
    <default value, and optional special meaning>
    <more details, if any>

For example:

CURRENTLY
vacuum_cost_delay (floating point)

The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. The default value is 0, which disables the cost-based
vacuum delay feature. Positive values enable cost-based vacuuming.

When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, perhaps less than 1
millisecond. While vacuum_cost_delay can be set to
fractional-millisecond values, such delays may not be measured
accurately on older platforms. On such platforms, increasing VACUUM's
throttled resource consumption above what you get at 1ms will require
changing the other vacuum cost parameters. You should, nonetheless,
keep vacuum_cost_delay as small as your platform will consistently
measure; large delays are not helpful.

SUGGESTION
vacuum_cost_delay (floating point)

The amount of time that the process will sleep when the cost limit has
been exceeded. If this value is specified without units, it is taken
as milliseconds. Positive values enable cost-based vacuuming.

The default value is 0, which disables the cost-based vacuum delay feature.

When using cost-based vacuuming, appropriate values for
vacuum_cost_delay are usually quite small, ... blah blah

~~~

Thoughts?

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

---

From: Vladlen Popolitov <[email-masked]>
Date: Fri, 07 Feb 2025 14:39:33 +0700

Marcos Pegoraro писал(а) 2025-02-06 04:07:
> Reading DOCs sometimes is boring because you want to know only the
> default value of something. I know what that GUC is, I know how to
> change it, I only don't remember what its default value is. Then you
> have to read that entire paragraph just to read that the default value
> is ...
> 
Hi
It looks helpful.
+1 from me.
-- 
Best regards,

Vladlen Popolitov.

---

From: Marcos Pegoraro <[email-masked]>
Date: Wed, 14 May 2025 17:40:56 -0300

Well, I don't know if you like it, but here it is.

What I'm trying to do here is put some standard on how variables are
described, because they have lots of ways they are described.
What way is better is to be discussed but I think they are confused because
they were written at different times by different people.
The explaining part sometimes starts with default value, sometimes default
is the last thing, sometimes it doesn't exist at all.
Additionally there is no explanation about read only variables.

These are examples explaining these different ways of writing:

No default value
 - restrict_nonsystem_relation_kind
 - local_preload_libraries, session_preload_libraries and
shared_preload_libraries
 - gin_fuzzy_search_limit
 - quote_all_identifiers
 - data_checksums
 - num_os_semaphores
 - archive_mode
 - archive_timeout
 - restore_command
Default value is written twice
 - transform_null_equals
Values written in different ways
 - '' vs empty string
 - one thousand files vs 1000 files
 - The default is five transactions vs The default is five minutes
(<literal>5min</literal>).
 - The default value is <literal>10.0</literal> vs The default value is 100
buffers
 - 128 megabytes vs 128MB vs two megabytes
 - If this parameter is off (the default) vs Default is off
 - The default is zero (<literal>0</literal>) vs The default value is
<literal>0</literal>
 - <literal>-1</literal> (the default) means vs A value of zero (the
default) disables

regards
Marcos