More foreign table documentation improvements.

Shigeru Hanada, with some additional wordsmithing by me

doc/src/sgml/ddl.sgml

@@ -3021,10 +3021,11 @@ ANALYZE measurement;
     <firstterm>foreign data wrapper</firstterm>. A foreign data wrapper is a
     library that can communicate with an external data source, hiding the
     details of connecting to the data source and fetching data from it. There
-    are several foreign data wrappers available, which can for example read
+    is a foreign data wrapper available as a <file>contrib</file> module,
-    plain data files residing on the server, or connect to another PostgreSQL
+    which can read plain data files residing on the server.  Other kind of
-    instance. If none of the existing foreign data wrappers suit your needs,
+    foreign data wrappers might be found as third party products.  If none of
-    you can write your own; see <xref linkend="fdwhandler">.
+    the existing foreign data wrappers suit your needs, you can write your
+    own; see <xref linkend="fdwhandler">.
    </para>
 
    <para>

doc/src/sgml/fdwhandler.sgml

@@ -179,6 +179,17 @@ IterateForeignScan (ForeignScanState *node);
      are not needed, you should insert nulls in those column positions.
     </para>
 
+    <para>
+     Note that <productname>PostgreSQL</productname>'s executor doesn't care
+     whether the rows returned violate the <literal>NOT NULL</literal>
+     constraints which were defined on the foreign table columns - but the
+     planner does care, and may optimize queries incorrectly if
+     <literal>NULL</> values are present in a column declared not to contain
+     them.  If a <literal>NULL</> value is encountered when the user has
+     declared that none should be present, it may be appropriate to raise an
+     error (just as you would need to do in the case of a data type mismatch).
+    </para>
+
     <para>
 <programlisting>
 void