Re: Better visualization of default values

On Thu, Feb 6, 2025 at 10:46 PM Marcos Pegoraro <marcos(at)f10(dot)com(dot)br> wrote:
>
> I agree that duplicating default values is not fine, I can remove them from the explanation and put it only near definition.
>
> But about adding a new line with its default value, sometimes is fine, sometimes not.
> [1] is a good example which would be fine but the next ones cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost and so on wouldn't be good.
>
> And obviously, if you don't know the purpose of that GUC, you'll have to read the entire paragraph to understand it.
> Objective here is to those ones who know what it is, but don't remember its default.
>

If you feel a blank line preceding the default in the description is
sometimes inappropriate then forget that; just ensure the default
information is consistently *last* in the GUC short description
paragraph.

Like this:

<guc-name> (type)
<short description><default value>
<more details, if any>

Then.
- No duplicated info
- Locating the default info is effortless (the $SUBJECT goal) because
they are always found in the same place.
- Many descriptions are using this format already (e.g.
cpu_tuple_cost, cpu_index_tuple_cost, cpu_operator_cost etc) so there
is nothing to do for these.

~~~

+1 to your second goal of wanting to use consistent wording [1]

======
[1] https://www.postgresql.org/message-id/CAB-JLwa1BwESd_OJZftOeaw4dSCg29rd1nhc3gLwYZ1N8yxwrw%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

> [1] - https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-RANDOM-PAGE-COST
>
> regards
> Marcos
>
> Em qua., 5 de fev. de 2025 às 20:59, Peter Smith <smithpb2250(at)gmail(dot)com> escreveu:
>>
>> 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