pgsql: Describe special values in GUC descriptions more consistently.

From: Nathan Bossart <nathan(at)postgresql(dot)org>
To: pgsql-committers(at)lists(dot)postgresql(dot)org
Subject: pgsql: Describe special values in GUC descriptions more consistently.
Date: 2025-02-14 16:45:31
Message-ID: E1tiyol-0076of-2Z@gemulon.postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-committers

Describe special values in GUC descriptions more consistently.

Many GUCs accept special values like -1 or an empty string to
disable the feature, use a system default, etc. While the
documentation consistently lists these special values, the GUC
descriptions do not. Many such descriptions fail to mention the
special values, and those that do vary in phrasing and placement.
This commit aims to bring some consistency to this area by applying
the following rules:

* Special values should be listed at the end of the long
description.
* Descriptions should use numerals (e.g., "0") instead of words
(e.g., "zero").
* Special value mentions should be concise and direct (e.g., "0
disables the timeout.", "An empty string means use the operating
system setting.").
* Multiple special values should be listed in ascending order.

Of course, there are exceptions, such as
max_pred_locks_per_relation and search_path, whose special values
are too complex to include. And there are cases like
listen_addresses, where the meaning of an empty string is arguably
too obvious to include. In those cases, I've refrained from adding
special value information to the GUC description.

Reviewed-by: Peter Smith <smithpb2250(at)gmail(dot)com>
Reviewed-by: "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>
Reviewed-by: Daniel Gustafsson <daniel(at)yesql(dot)se>
Discussion: https://postgr.es/m/Z6aIy4aywxUZHAo6%40nathan

Branch
------
master

Details
-------
https://git.postgresql.org/pg/commitdiff/977d865c36cc6ed4e813b8545b09d06f51534011

Modified Files
--------------
src/backend/utils/misc/guc_tables.c | 139 ++++++++++++++++++------------------
src/include/utils/guc_tables.h | 15 ++++
2 files changed, 84 insertions(+), 70 deletions(-)

Browse pgsql-committers by date

  From Date Subject
Next Message Melanie Plageman 2025-02-14 17:59:17 pgsql: Convert heap_vac_scan_next_block() boolean parameters to flags
Previous Message Daniel Gustafsson 2025-02-14 11:11:40 pgsql: Fix assertion on dereferenced object