Doc: rearrange high-level commentary about node support coverage.

copyfuncs.c and friends no longer seem like great places to put
high-level remarks about what's covered and what isn't.  Move that
material to backend/nodes/README and other more-prominent places.
Add back (versions of) some remarks that disappeared in 2be87f092.

Discussion: https://postgr.es/m/3843645.1657385930@sss.pgh.pa.us

3 files changed, 26 insertions, 19 deletions

diff --git a/src/backend/nodes/README b/src/backend/nodes/README
index b3dc9afaf77..64937fe254b 100644
--- a/src/backend/nodes/README
+++ b/src/backend/nodes/README
@@ -6,10 +6,34 @@ Node Structures
 Introduction
 ------------
 
+Postgres uses "node" types to organize parse trees, plan trees, and
+executor state trees.  All objects that can appear in such trees must
+be declared as node types.  In addition, a few object types that aren't
+part of parse/plan/execute node trees receive NodeTags anyway for
+identification purposes, usually because they are involved in APIs
+where we want to pass multiple object types through the same pointer.
+
 The node structures are plain old C structures with the first field
 being of type NodeTag.  "Inheritance" is achieved by convention:
 the first field can alternatively be of another node type.
 
+Node types typically have support for being copied by copyObject(),
+compared by equal(), serialized by outNode(), and deserialized by
+nodeRead().  For some classes of Nodes, not all of these support
+functions are required; for example, executor state nodes don't
+presently need any of them.  So far as the system is concerned,
+output and read functions are only needed for node types that can
+appear in parse trees stored in the catalogs, and for plan tree
+nodes because those are serialized to be passed to parallel workers.
+However, we provide output functions for some other node types as well,
+because they are very handy for debugging.  Currently, such coverage
+exists for raw parsetrees and most planner data structures.  However,
+output coverage of raw parsetrees is incomplete: in particular, utility
+statements are almost entirely unsupported.
+
+Relevant Files
+--------------
+
 Utility functions for manipulating node structures reside in this
 directory.  Some support functions are automatically generated by the
 gen_node_support.pl script, other functions are maintained manually.
@@ -40,7 +64,7 @@ FILES IN THIS DIRECTORY (src/backend/nodes/)
 
 FILES IN src/include/nodes/
 
-    Node definitions:
+    Node definitions primarily appear in:
 	nodes.h		- define node tags (NodeTag) (*)
 	primnodes.h	- primitive nodes
 	parsenodes.h	- parse tree nodes
diff --git a/src/backend/nodes/outfuncs.c b/src/backend/nodes/outfuncs.c
index 9e70bbb4d69..4d776e7b51b 100644
--- a/src/backend/nodes/outfuncs.c
+++ b/src/backend/nodes/outfuncs.c
@@ -10,19 +10,6 @@
  * IDENTIFICATION
  *	  src/backend/nodes/outfuncs.c
  *
- * NOTES
- *	  Every node type that can appear in stored rules' parsetrees *must*
- *	  have an output function defined here (as well as an input function
- *	  in readfuncs.c).  In addition, plan nodes should have input and
- *	  output functions so that they can be sent to parallel workers.
- *
- *	  For use in debugging, we also provide output functions for nodes
- *	  that appear in raw parsetrees and planner Paths.  These node types
- *	  need not have input functions.  Output support for raw parsetrees
- *	  is somewhat incomplete, too; in particular, utility statements are
- *	  almost entirely unsupported.  We try to support everything that can
- *	  appear in a raw SELECT, though.
- *
  *-------------------------------------------------------------------------
  */
 #include "postgres.h"
diff --git a/src/backend/nodes/readfuncs.c b/src/backend/nodes/readfuncs.c
index 67b0f798c15..1421686938f 100644
--- a/src/backend/nodes/readfuncs.c
+++ b/src/backend/nodes/readfuncs.c
@@ -11,16 +11,12 @@
  *	  src/backend/nodes/readfuncs.c
  *
  * NOTES
- *	  Path nodes do not have any readfuncs support, because we never
- *	  have occasion to read them in.  (There was once code here that
- *	  claimed to read them, but it was broken as well as unused.)  We
- *	  never read executor state trees, either.
- *
  *	  Parse location fields are written out by outfuncs.c, but only for
  *	  debugging use.  When reading a location field, we normally discard
  *	  the stored value and set the location field to -1 (ie, "unknown").
  *	  This is because nodes coming from a stored rule should not be thought
  *	  to have a known location in the current query's text.
+ *
  *	  However, if restore_location_fields is true, we do restore location
  *	  fields from the string.  This is currently intended only for use by the
  *	  WRITE_READ_PARSE_PLAN_TREES test code, which doesn't want to cause