Clarify the distinction between public and private SPITupleTable fields.

The fields that we consider public are "tupdesc" and "vals", which
historically are in the middle of the struct.  Move them to the front
(this should be perfectly safe to do in HEAD) and add comments to make
it quite clear which fields are public or not.

Also adjust spi.sgml's documentation of the struct to match.
That doc had bit-rotted somewhat, as it was missing some fields.
(Arguably we should just remove all the private fields from the docs,
but for now I refrained.)

Daniel Gustafsson, reviewed by Fabien Coelho

Discussion: https://postgr.es/m/0D19F836-B743-4340-B6A2-F148CA3DD1F0@yesql.se

doc/src/sgml/spi.sgml

@@ -318,21 +318,26 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
    The structure <structname>SPITupleTable</structname> is defined
    thus:
 <programlisting>
-typedef struct
+typedef struct SPITupleTable
 {
+    /* Public members */
+    TupleDesc   tupdesc;        /* tuple descriptor */
+    HeapTuple  *vals;           /* array of tuples */
+
+    /* Private members, not intended for external callers */
     MemoryContext tuptabcxt;    /* memory context of result table */
-    uint64      alloced;        /* number of alloced vals */
+    uint64      alloced;        /* # of alloced vals */
-    uint64      free;           /* number of free vals */
+    uint64      free;           /* # of free vals */
-    TupleDesc   tupdesc;        /* row descriptor */
+    slist_node  next;           /* link for internal bookkeeping */
-    HeapTuple  *vals;           /* rows */
+    SubTransactionId subid;     /* subxact in which tuptable was created */
 } SPITupleTable;
 </programlisting>
+   <structfield>vals</structfield> and <structfield>tupdesc</structfield> can
+   be used by SPI callers, the remaining fields are internal.
    <structfield>vals</structfield> is an array of pointers to rows.  (The number
    of valid entries is given by <varname>SPI_processed</varname>.)
    <structfield>tupdesc</structfield> is a row descriptor which you can pass to
-   SPI functions dealing with rows.  <structfield>tuptabcxt</structfield>,
+   SPI functions dealing with rows.
-   <structfield>alloced</structfield>, and <structfield>free</structfield> are internal
-   fields not intended for use by SPI callers.
   </para>
 
   <para>

src/include/executor/spi.h

@@ -21,11 +21,14 @@
 
 typedef struct SPITupleTable
 {
+	/* Public members */
+	TupleDesc	tupdesc;		/* tuple descriptor */
+	HeapTuple  *vals;			/* array of tuples */
+
+	/* Private members, not intended for external callers */
 	MemoryContext tuptabcxt;	/* memory context of result table */
 	uint64		alloced;		/* # of alloced vals */
 	uint64		free;			/* # of free vals */
-	TupleDesc	tupdesc;		/* tuple descriptor */
-	HeapTuple  *vals;			/* tuples */
 	slist_node	next;			/* link for internal bookkeeping */
 	SubTransactionId subid;		/* subxact in which tuptable was created */
 } SPITupleTable;