From: Nathan Bossart <nathan@postgresql.org>
To: pgsql-committers@lists.postgresql.org
Subject: pgsql: Describe special values in GUC descriptions more consistently.
Date: Fri, 14 Feb 2025 16:45:31 +0000
Message-ID: <E1tiyol-0076of-2Z@gemulon.postgresql.org> (raw)
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@gmail.com>
Reviewed-by: "David G. Johnston" <david.g.johnston@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.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(-)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-committers@postgresql.org
Cc: nathan@postgresql.org, pgsql-committers@lists.postgresql.org
Subject: Re: pgsql: Describe special values in GUC descriptions more consistently.
In-Reply-To: <E1tiyol-0076of-2Z@gemulon.postgresql.org>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox