Re: Better visualization of default values

On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <marcos(at)f10(dot)com(dot)br> 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 ...
>
> So, what you think about this.
> It's not complete but you can see if it's useful or not
>

+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