Doc: clarify that DROP ... CASCADE is recursive.

Apparently that's not obvious to everybody, so let's belabor the point.

In passing, document that DROP POLICY has CASCADE/RESTRICT options (which
it does, per gram.y) but they do nothing (I assume, anyway).  Also update
some long-obsolete commentary in gram.y.

Discussion: <20160805104837.1412.84915@wrigleys.postgresql.org>

Author: tglsfdc

doc/src/sgml/ddl.sgml

@@ -2611,7 +2611,7 @@ VALUES ('Albany', NULL, NULL, 'NY');
    if they are inherited
    from any parent tables. If you wish to remove a table and all of its
    descendants, one easy way is to drop the parent table with the
-   <literal>CASCADE</literal> option.
+   <literal>CASCADE</literal> option (see <xref linkend="ddl-depend">).
   </para>
 
   <para>
@@ -3586,20 +3586,22 @@ HINT:  Use DROP ... CASCADE to drop the dependent objects too.
 <screen>
 DROP TABLE products CASCADE;
 </screen>
-   and all the dependent objects will be removed.  In this case, it
-   doesn't remove the orders table, it only removes the foreign key
-   constraint.  (If you want to check what <command>DROP ... CASCADE</> will do,
+   and all the dependent objects will be removed, as will any objects
+   that depend on them, recursively.  In this case, it doesn't remove
+   the orders table, it only removes the foreign key constraint.
+   It stops there because nothing depends on the foreign key constraint.
+   (If you want to check what <command>DROP ... CASCADE</> will do,
    run <command>DROP</> without <literal>CASCADE</> and read the
    <literal>DETAIL</> output.)
   </para>
 
   <para>
-   All <command>DROP</> commands in <productname>PostgreSQL</> support
+   Almost all <command>DROP</> commands in <productname>PostgreSQL</> support
    specifying <literal>CASCADE</literal>.  Of course, the nature of
    the possible dependencies varies with the type of the object.  You
    can also write <literal>RESTRICT</literal> instead of
    <literal>CASCADE</literal> to get the default behavior, which is to
-   prevent the dropping of objects that other objects depend on.
+   prevent dropping objects that any other objects depend on.
   </para>
 
   <note>
@@ -3613,6 +3615,15 @@ DROP TABLE products CASCADE;
    </para>
   </note>
 
+  <para>
+   If a <command>DROP</> command lists multiple
+   objects, <literal>CASCADE</literal> is only required when there are
+   dependencies outside the specified group.  For example, when saying
+   <literal>DROP TABLE tab1, tab2</literal> the existence of a foreign
+   key referencing <literal>tab1</> from <literal>tab2</> would not mean
+   that <literal>CASCADE</literal> is needed to succeed.
+  </para>
+
   <para>
    For user-defined functions, <productname>PostgreSQL</productname> tracks
    dependencies associated with a function's externally-visible properties,

doc/src/sgml/ref/alter_domain.sgml

@@ -212,7 +212,9 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
       <term><literal>CASCADE</literal></term>
       <listitem>
        <para>
-        Automatically drop objects that depend on the constraint.
+        Automatically drop objects that depend on the constraint,
+        and in turn all objects that depend on those objects
+        (see <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/alter_foreign_table.sgml

@@ -431,7 +431,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceab
       <listitem>
        <para>
         Automatically drop objects that depend on the dropped column
-        or constraint (for example, views referencing the column).
+        or constraint (for example, views referencing the column),
+        and in turn all objects that depend on those objects
+        (see <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/alter_table.sgml

@@ -823,7 +823,9 @@ ALTER TABLE ALL IN TABLESPACE <replaceable class="PARAMETER">name</replaceable>
       <listitem>
        <para>
         Automatically drop objects that depend on the dropped column
-        or constraint (for example, views referencing the column).
+        or constraint (for example, views referencing the column),
+        and in turn all objects that depend on those objects
+        (see <xref linkend="ddl-depend">).
        </para>
       </listitem>
      </varlistentry>

doc/src/sgml/ref/drop_access_method.sgml

@@ -62,7 +62,9 @@ DROP ACCESS METHOD [ IF EXISTS ] <replaceable class="parameter">name</replaceabl
     <listitem>
      <para>
       Automatically drop objects that depend on the access method
-      (such as operator classes, operator families, indexes).
+      (such as operator classes, operator families, and indexes),
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_aggregate.sgml

@@ -107,7 +107,10 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      Automatically drop objects that depend on the aggregate function.
+      Automatically drop objects that depend on the aggregate function
+      (such as views using it),
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_collation.sgml

@@ -60,7 +60,9 @@ DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRIC
      <term><literal>CASCADE</literal></term>
      <listitem>
       <para>
-       Automatically drop objects that depend on the collation.
+       Automatically drop objects that depend on the collation,
+       and in turn all objects that depend on those objects
+       (see <xref linkend="ddl-depend">).
       </para>
      </listitem>
     </varlistentry>

doc/src/sgml/ref/drop_domain.sgml

@@ -62,7 +62,9 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [, .
     <listitem>
      <para>
       Automatically drop objects that depend on the domain (such as
-      table columns).
+      table columns),
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_event_trigger.sgml

@@ -63,7 +63,9 @@ DROP EVENT TRIGGER [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceabl
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      Automatically drop objects that depend on the trigger.
+      Automatically drop objects that depend on the trigger,
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>

doc/src/sgml/ref/drop_extension.sgml

@@ -66,7 +66,9 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable> [
     <term><literal>CASCADE</literal></term>
     <listitem>
      <para>
-      Automatically drop objects that depend on the extension.
+      Automatically drop objects that depend on the extension,
+      and in turn all objects that depend on those objects
+      (see <xref linkend="ddl-depend">).
      </para>
     </listitem>
    </varlistentry>