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/[email protected]

4 files changed, 41 insertions, 25 deletions

diff --git a/src/backend/nodes/README b/src/backend/nodes/README
index b3dc9afaf7..64937fe254 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 9e70bbb4d6..4d776e7b51 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 67b0f798c1..1421686938 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
diff --git a/src/include/nodes/execnodes.h b/src/include/nodes/execnodes.h
index 967604b8a5..01b1727fc0 100644
--- a/src/include/nodes/execnodes.h
+++ b/src/include/nodes/execnodes.h
@@ -3,11 +3,20 @@
  * execnodes.h
  *	  definitions for executor state nodes
  *
- * ExprState represents the evaluation state for a whole expression tree.
- * Most Expr-based plan nodes do not have a corresponding expression state
- * node, they're fully handled within execExpr* - but sometimes the state
- * needs to be shared with other parts of the executor, as for example
- * with SubPlanState, which nodeSubplan.c has to modify.
+ * Most plan node types declared in plannodes.h have a corresponding
+ * execution-state node type declared here.  An exception is that
+ * expression nodes (subtypes of Expr) are usually represented by steps
+ * of an ExprState, and fully handled within execExpr* - but sometimes
+ * their state needs to be shared with other parts of the executor, as
+ * for example with SubPlanState, which nodeSubplan.c has to modify.
+ *
+ * Node types declared in this file do not have any copy/equal/out/read
+ * support.  (That is currently hard-wired in gen_node_support.pl, rather
+ * than being explicitly represented by pg_node_attr decorations here.)
+ * There is no need for copy, equal, or read support for executor trees.
+ * Output support could be useful for debugging; but there are a lot of
+ * specialized fields that would require custom code, so for now it's
+ * not provided.
  *
  *
  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
@@ -53,7 +62,7 @@ struct LogicalTapeSet;
 /* ----------------
  *		ExprState node
  *
- * ExprState is the top-level node for expression evaluation.
+ * ExprState represents the evaluation state for a whole expression tree.
  * It contains instructions (in ->steps) to evaluate the expression.
  * ----------------
  */