nocfbot-v18-0007-pgstashadvice-sgml.diff

diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 62af2b21fd7..8f09d728698 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -151,7 +151,6 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
  &ltree;
  &pageinspect;
  &passwordcheck;
- &pgstashadvice;
  &pgbuffercache;
  &pgcollectadvice;
  &pgcrypto;
@@ -161,6 +160,7 @@ CREATE EXTENSION <replaceable>extension_name</replaceable>;
  &pgplanadvice;
  &pgprewarm;
  &pgrowlocks;
+ &pgstashadvice;
  &pgstatstatements;
  &pgstattuple;
  &pgsurgery;
diff --git a/doc/src/sgml/pgstashadvice.sgml b/doc/src/sgml/pgstashadvice.sgml
index d1878f4f7c1..79b89beba38 100644
--- a/doc/src/sgml/pgstashadvice.sgml
+++ b/doc/src/sgml/pgstashadvice.sgml
@@ -10,7 +10,7 @@
  <para>
   The <filename>pg_stash_advice</filename> extension allows you to stash
   <link linkend="pgplanadvice">plan advice</link> strings in dynamic
-  shared memory where they can be automatically applied.  An
+  shared memory where they can be automatically applied. An
   <literal>advice stash</literal> is a mapping from
   <link linkend="guc-compute-query-id">query identifiers</link> to plan advice
   strings. Whenever a session is asked to plan a query whose query ID appears
@@ -25,7 +25,7 @@
   In order to use this module, you will need to execute
   <literal>CREATE EXTENSION pg_stash_advice</literal> in at least
   one database, so that you have access to the SQL functions to manage
-  advice stashes.  You will also need the <literal>pg_stash_advice</literal>
+  advice stashes. You will also need the <literal>pg_stash_advice</literal>
   module to be loaded in all sessions where you want this module to
   automatically apply advice. It will usually be best to do this by adding
   <literal>pg_stash_advice</literal> to
@@ -54,12 +54,12 @@
   string that you wish to store for each query. One way to do this is to use
   <literal>EXPLAIN</literal>: the <literal>VERBOSE</literal> option will
   show the query ID, and the <literal>PLAN_ADVICE</literal> option will
-  show plan advice.  <xref linkend="pgcollectadvice" /> can be used to
+  show plan advice. <xref linkend="pgcollectadvice" /> can be used to
   obtain this information for an entire workload, although care must be
   taken since it can use up a lot of memory very quickly. Query identifiers can
   also be obtained through tools such as <xref linkend="pgstatstatements" />
   or <xref linkend="monitoring-pg-stat-activity-view" />, but these tools
-  will not provide plan advice strings.  Note that
+  will not provide plan advice strings. Note that
   <xref linkend="guc-compute-query-id" /> must be enabled for query
   identifiers to be computed; if set to <literal>auto</literal>, loading
   <literal>pg_stash_advice</literal> will enable it automatically.
@@ -84,7 +84,9 @@
   <literal>pg_stash_advice.stash_name</literal> for their session, and this
   may reveal the contents of any advice stash with that name. Users should
   assume that information embedded in stashed advice strings may become visible
-  to nonprivileged users.
+  to nonprivileged users. However, advice targets are the only explicit
+  userspace data present in advice strings and most catalog contents are
+  considered non-privileged in PostgreSQL.
  </para>
 
  <sect2 id="pgstashadvice-functions">
@@ -102,7 +104,8 @@
 
     <listitem>
      <para>
-      Creates a new, empty advice stash with the given name.
+      Creates a new, empty advice stash with the given name, which must not be
+      zero length.
      </para>
     </listitem>
    </varlistentry>
@@ -134,10 +137,13 @@
     <listitem>
      <para>
       Stores an advice string in the named advice stash, associated with
-      the given query identifier.  If an entry for that query identifier
-      already exists in the stash, it is replaced.  If
+      the given query identifier. If an entry for that query identifier
+      already exists in the stash, it is replaced. If
       <parameter>advice_string</parameter> is <literal>NULL</literal>,
-      any existing entry for that query identifier is removed.
+      any existing entry for that query identifier is removed. A zero length advice
+      string is stored in the stash. An error is raised if stash_name does
+      not exist. Passing NULL for the query identifier results in a silent no-op,
+      and passing 0 is not permitted, but otherwise, any bigint value is accepted.
      </para>
     </listitem>
    </varlistentry>
@@ -170,7 +176,7 @@
 
     <listitem>
      <para>
-      Returns one row for each entry in the named advice stash.  If
+      Returns one row for each entry in the named advice stash. If
       <parameter>stash_name</parameter> is <literal>NULL</literal>, returns
       entries from all stashes.
      </para>
@@ -197,7 +203,7 @@
     <listitem>
      <para>
       Specifies the name of the advice stash to consult during query
-      planning.  The default value is the empty string, which disables
+      planning. The default value is the empty string, which disables
       this module.
      </para>
     </listitem>