v1-0001-docs-improve-custom-settings.patch

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 934ef5e469..4478d0aa91 100644
--- a/doc/src/sgml/config.sgml
+++ b/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>
@@ -11350,14 +11350,20 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$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">
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ad663c94d7..605bf533ee 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -28157,7 +28157,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
@@ -28191,6 +28191,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>
         <literal>set_config('log_statement_stats', 'off', false)</literal>
         <returnvalue>off</returnvalue>