From 7644c506305336cf643101593d0b3ca7461f5469 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <daniel@yesql.se>
Date: Wed, 17 Jul 2019 13:54:02 +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. In order to make the separation between
public and private members clearer, reorder the struct with public
and private members separate.

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.
---
 doc/src/sgml/spi.sgml      | 17 +++++++++++------
 src/include/executor/spi.h |  7 +++++--
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index 66eced6c94..cfc3ae251e 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 */
+    /* 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