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. [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 <smithpb2...@gmail.com> escreveu: > On Thu, Feb 6, 2025 at 8:08 AM Marcos Pegoraro <mar...@f10.com.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 >
