[patch] [doc] Clarify that signal functions have no feedback

Hackers,

Over in Bug# 16652 [1] Christoph failed to recognize the fact that signal
sending functions are inherently one-way just as signals are.  It seems
worth heading off this situation in the future by making it clear how
signals behave and, in the specific case of pg_reload_conf, that the
important feedback one would hope to get out of a success/failure response
from the function call must instead be found in other locations.

Please see the attached patch, included inline as well.

David J.

[1]
https://www.postgresql.org/message-id/flat/16652-58dd6028047058a6%40postgresql.org

commit 6f0ba7c8fd131c906669882e4402930e548e4522
Author: David G. Johnston <david.g.johnston@gmail.com>
Date:   Mon Oct 12 22:35:38 2020 +0000

    Clarify that signal functions have no feedback

    Bug# 16652 complains that the definition of success for pg_reload_conf
    doesn't include the outcome of actually reloading the configuration
    files.  While this is a fairly easy gap to cross given knowledge of
    signals, being more explicit here doesn't hurt.

    Additionally, because of the special nature of pg_reload_conf, add
    links to the various locations where information related to the
    success or failure of a reload can be found.  Lacking an existing
    holistic location in the documentation to point the reader just
    list the three resources explicitly.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index e7cff980dd..75ff8acc93 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -23927,7 +23927,8 @@ SELECT collation for ('foo' COLLATE "de_DE");

    <para>
     The functions shown in <xref
-    linkend="functions-admin-signal-table"/> send control signals to
+    linkend="functions-admin-signal-table"/> send uni-directional
+    control signals to
     other server processes.  Use of these functions is restricted to
     superusers by default but access may be granted to others using
     <command>GRANT</command>, with noted exceptions.
@@ -23935,7 +23936,8 @@ SELECT collation for ('foo' COLLATE "de_DE");

    <para>
     Each of these functions returns <literal>true</literal> if
-    successful and <literal>false</literal> otherwise.
+    the signal was successfully sent and <literal>false</literal>
+    if the sending of the signal failed.
    </para>

    <table id="functions-admin-signal-table">
@@ -23983,7 +23985,14 @@ SELECT collation for ('foo' COLLATE "de_DE");
         server to reload their configuration files.  (This is initiated by
         sending a <systemitem>SIGHUP</systemitem> signal to the postmaster
         process, which in turn sends <systemitem>SIGHUP</systemitem> to
each
-        of its children.)
+        of its children.)  Inspection of the
+        <link linkend="runtime-config-logging">log file</link>,
+        <link linkend="view-pg-file-settings">pg_file_settings view</link>,
+        and the
+        <link linkend="view-pg-settings">pg_settings view</link>,
+        is recommended before and/or after executing
+        this function to detect whether there are any issues in the
configuration
+        files preventing some of all of their setting changes from taking
effect.
        </para></entry>
       </row>