describe special values in GUC descriptions more consistently
Nathan Bossart <nathandbossart@gmail.com>
From: Nathan Bossart <nathandbossart@gmail.com>
To: pgsql-hackers@postgresql.org
Date: 2025-02-07T22:27:23Z
Lists: pgsql-hackers
Attachments
For many GUCs, special values like -1, "", etc. have some sort of special meaning, such as disabling the feature. While the documentation seems to be reasonably good about listing special values, the GUC descriptions are less consistent. Many GUC descriptions don't state the special values at all, and the ones that do are inconsistent in phrasing and placement (e.g., a couple list them in the short description, but most list them in the long description). I figured I'd try to add some consistency here. In the attached patch, I've attempted to apply the following proposed rules to the descriptions of GUCs that accept special values: * The special values should be listed at the end of the long description. * Descriptions should use numerals (0) instead of words (zero). * The special value notes should be consistently worded and as direct as possible (e.g., "0 disables the timeout.", "An empty string means to use the system setting."). There are a few exceptions, such as max_pred_locks_per_relation and search_path, where the special values are too complicated to include. And there are cases like unix_socket_directories, listen_addresses, application_name, and cluster_name, where the meaning of "" is arguably too obvious to bother including. There's a good chance that I've missed a couple, too. Thoughts? -- nathan
Commits
-
Adjust auto_explain's GUC descriptions.
- e636da920028 18.0 landed
-
Describe special values in GUC descriptions more consistently.
- 977d865c36cc 18.0 landed