From 9c0985edece22bd3e1c9c4f0c921dde99f14574e Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Fri, 14 Jun 2019 12:38:11 +0200
Subject: [PATCH] Add missing members to SPITupleTable documentation

Commit 3d13623d75d3206c8f009353415043a191ebab39 added the next and
subid fields to the SPITupleTable struct, but they never made it
into the documentation. While these are internal members, we already
document several other internal ones so add these too to make the
documentation match reality.  Also reorder the members to separate
the public from the private fields.

Since this makes the number of internal members far outnumber the
public ones, also reword the statement about which fields can be
used to improve clarity.

fixup
---
 doc/src/sgml/spi.sgml      | 21 +++++++++++++--------
 src/include/executor/spi.h |  7 +++++--
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 66eced6c94..37fe11b4f5 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -320,19 +320,24 @@ SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
 <programlisting>
 typedef struct
 {
-    MemoryContext tuptabcxt;    /* memory context of result table */
-    uint64      alloced;        /* number of alloced vals */
-    uint64      free;           /* number of free vals */
-    TupleDesc   tupdesc;        /* row descriptor */
-    HeapTuple  *vals;           /* rows */
+    /* Public members */
+    TupleDesc	tupdesc;		/* row descriptor */
+    HeapTuple  *vals;			/* rows */
+
+    /* Private members, not intended for external callers */
+    MemoryContext tuptabcxt;	/* memory context of result table */
+    uint64		alloced;		/* # of alloced vals */
+    uint64		free;			/* # of free vals */
+    slist_node	next;			/* link for internal bookkeeping */
+    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>,
-   <structfield>alloced</structfield>, and <structfield>free</structfield> are internal
-   fields not intended for use by SPI callers.
+   SPI functions dealing with rows.
   </para>
 
   <para>
diff --git a/src/include/executor/spi.h b/src/include/executor/spi.h
index 7bf361874d..b3dfe30f4e 100644
--- a/src/include/executor/spi.h
+++ b/src/include/executor/spi.h
@@ -21,11 +21,14 @@
 
 typedef struct SPITupleTable
 {
+	/* Public members */
+	TupleDesc	tupdesc;		/* tuple descriptor */
+	HeapTuple  *vals;			/* 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;
-- 
2.14.1.145.gb3622a4ee