On Sat, Feb 8, 2025 at 9:27 AM Nathan Bossart <nathandboss...@gmail.com> wrote: > > 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? >
+1 for improving consistency. ====== Some patch observations and nits. 1. IMO all places wording as "XXX means to YYY" should be just "XXX means YYY" (e.g. remove the "to") e.g. "-1 means to wait forever." => "-1 means wait forever." e.g. ""-1 means to log values in full." => "-1 means log values in full." ~~~ 2. GUC names in messages should always be double quoted. ~~~ 3. Wording for the automatic selections. Some of the special values get calculated and assigned *automatically* on your behalf. The patch currently seems to be using "means to use" for these: I felt all these should be written as: "XXX means to use YYY" => "XXX means YYY is used." e.g. "0 means to use a suitable default value." => "0 means a suitable default value is used." e.g. "0 means to use a fraction of \"shared_buffers\"." => "0 means a fraction of \"shared_buffers\" is used". e.g. "-1 means to use vacuum_cost_limit" => "-1 means \"vacuum_cost_limit\" is used." ~~ 4. When there are multiple special values, it seems more natural if the values are ordered. Maybe just personal preference. e.g. "0 means to log all files. -1 disables temporary file logs." => "-1 disables temporary file logs. 0 means log all files." ====== Kind Regards, Peter Smith. Fujitsu Australia.
