[CF 5548] v1 - Document custom settings more consistently

This branch was automatically generated by a robot using patches from an
email thread registered at:

https://commitfest.postgresql.org/patch/5548

The branch will be overwritten each time a new patch version is posted to
the thread, and also periodically to check for bitrot caused by changes
on the master branch.

Patch(es): https://www.postgresql.org/message-id/CAKFQuwbh0Pt03JWiV1iCc23uyQU1KYfXAyCsm5UGnKM2=hz_SQ@mail.gmail.com
Author(s): David Johnston

Author: Commitfest Bot

doc/src/sgml/config.sgml

@@ -23,7 +23,7 @@
 
     <para>
      All parameter names are case-insensitive. Every parameter takes a
-     value of one of five types: boolean, string, integer, floating point,
+     non-null value of one of five types: boolean, string, integer, floating point,
      or enumerated (enum).  The type determines the syntax for setting the
      parameter:
     </para>
@@ -12018,14 +12018,20 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir'
     <para>
      Because custom options may need to be set in processes that have not
      loaded the relevant extension module, <productname>PostgreSQL</productname>
-     will accept a setting for any two-part parameter name.  Such variables
-     are treated as placeholders and have no function until the module that
-     defines them is loaded. When an extension module is loaded, it will add
+     will accept a setting for any two-part parameter name.
+     When an extension module is loaded, it will add
      its variable definitions and convert any placeholder values according to
      those definitions.  If there are any unrecognized placeholders
      that begin with its extension name, warnings are issued and those
      placeholders are removed.
     </para>
+
+    <para>
+     If a placeholder is created in a session it will exist for the
+     lifetime of the session unless removed by an extension.
+     Placeholders have a string data type with a reset value of the empty string.
+    </para>
+
    </sect1>
 
    <sect1 id="runtime-config-developer">

doc/src/sgml/func.sgml

@@ -28555,7 +28555,7 @@ acl      | {postgres=arwdDxtm/postgres,foo=r/postgres}
         <returnvalue>text</returnvalue>
        </para>
        <para>
-        Returns the current value of the
+        Returns the current non-null value of the
         setting <parameter>setting_name</parameter>.  If there is no such
         setting, <function>current_setting</function> throws an error
         unless <parameter>missing_ok</parameter> is supplied and
@@ -28589,6 +28589,17 @@ acl      | {postgres=arwdDxtm/postgres,foo=r/postgres}
         use <literal>false</literal> instead. This function corresponds to
         the SQL command <xref linkend="sql-set"/>.
        </para>
+       <para>
+        <function>set_config</function> accepts the NULL value for
+        <parameter>new_value</parameter>, but as settings cannot be null this input
+        is interpreted as a request to set the setting to its default value.
+       </para>
+       <para>
+        If <parameter>setting_name</parameter> does not already exist
+        <function>set_config</function> throws an error unless the identifier is a valid
+        <link linkend="runtime-config-custom">custom option</link> name, in which it
+        creates a placeholder with the empty string as its old value.
+       </para>
        <para>
         <function>set_config</function> accepts the NULL value for
         <parameter>new_value</parameter>, but as settings cannot be null, it