doc: Review for "Allow TRUNCATE command to truncate foreign tables".

Typos, corrections and language improvements in the docs.

Author: Justin Pryzby, Fujii Masao
Reviewed-by: Bharath Rupireddy, Justin Pryzby, Fujii Masao
Discussion: https://postgr.es/m/20210411041658.GB14564@telsasoft.com

doc/src/sgml/fdwhandler.sgml

@@ -1076,27 +1076,25 @@ ExecForeignTruncate(List *rels,
                     bool restart_seqs);
 </programlisting>
 
-     Truncate a set of foreign tables specified in <literal>rels</literal>.
+     Truncate foreign tables.  This function is called when
-     This function is called when <xref linkend="sql-truncate"/> is executed
+     <xref linkend="sql-truncate"/> is executed on a foreign table.
-     on foreign tables.  <literal>rels</literal> is the list of
+     <literal>rels</literal> is a list of <structname>Relation</structname>
-     <structname>Relation</structname> data structure that indicates
+     data structures of foreign tables to truncate.
-     a foreign table to truncate.
     </para>
 
     <para>
-     <literal>behavior</literal> defines how foreign tables should
+     <literal>behavior</literal> is either <literal>DROP_RESTRICT</literal>
-     be truncated, using as possible values <literal>DROP_RESTRICT</literal>,
+     or <literal>DROP_CASCADE</literal> indicating that the
-     which means that <literal>RESTRICT</literal> option is specified,
+     <literal>RESTRICT</literal> or <literal>CASCADE</literal> option was
-     and <literal>DROP_CASCADE</literal>, which means that
+     requested in the original <command>TRUNCATE</command> command,
-     <literal>CASCADE</literal> option is specified, in
+     respectively.
-     <command>TRUNCATE</command> command.
     </para>
     
     <para>
-     <literal>restart_seqs</literal> is set to <literal>true</literal>
+     If <literal>restart_seqs</literal> is <literal>true</literal>,
-     if <literal>RESTART IDENTITY</literal> option is specified in
+     the original <command>TRUNCATE</command> command requested the
-     <command>TRUNCATE</command> command.  It is <literal>false</literal>
+     <literal>RESTART IDENTITY</literal> behavior, otherwise the
-     if <literal>CONTINUE IDENTITY</literal> option is specified.
+     <literal>CONTINUE IDENTITY</literal> behavior was requested.
     </para>
 
     <para>
@@ -1109,11 +1107,10 @@ ExecForeignTruncate(List *rels,
     </para>
 
     <para>
-     <command>TRUNCATE</command> invokes
+     <function>ExecForeignTruncate</function> is invoked once per
-     <function>ExecForeignTruncate</function> once per foreign server
+     foreign server for which foreign tables are to be truncated.
-     that foreign tables to truncate belong to.  This means that all foreign
+     This means that all foreign tables included in <literal>rels</literal>
-     tables included in <literal>rels</literal> must belong to the same
+     must belong to the same server.
-     server.
     </para>
 
     <para>

doc/src/sgml/postgres-fdw.sgml

@@ -459,11 +459,17 @@ OPTIONS (ADD password_required 'false');
      <listitem>
       <para>
        This option controls whether <filename>postgres_fdw</filename> allows
-       foreign tables to be truncated using <command>TRUNCATE</command>
+       foreign tables to be truncated using the <command>TRUNCATE</command>
        command. It can be specified for a foreign table or a foreign server.
        A table-level option overrides a server-level option.
        The default is <literal>true</literal>.
       </para>
+
+      <para>
+       Of course, if the remote table is not in fact truncatable, an error
+       would occur anyway.  Use of this option primarily allows the error to
+       be thrown locally without querying the remote server.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>

doc/src/sgml/ref/truncate.sgml

@@ -173,7 +173,7 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [
 
   <para>
    <command>TRUNCATE</command> can be used for foreign tables if
-   the foreign data wrapper supports, for instance,
+   supported by the foreign data wrapper, for instance,
    see <xref linkend="postgres-fdw"/>.
   </para>
  </refsect1>