From: Tom Lane <tgl@sss.pgh.pa.us>
To: Daniel Gustafsson <daniel@yesql.se>
cc: pgsql-docs@lists.postgresql.org
Subject: Re: SPITupleTable members missing in docs
In-reply-to: <0D19F836-B743-4340-B6A2-F148CA3DD1F0@yesql.se>
References: <0D19F836-B743-4340-B6A2-F148CA3DD1F0@yesql.se>
Comments: In-reply-to Daniel Gustafsson <daniel@yesql.se>
	message dated "Fri, 14 Jun 2019 12:55:20 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <5147.1560521723.1@sss.pgh.pa.us>
Content-Transfer-Encoding: quoted-printable
Date: Fri, 14 Jun 2019 10:15:23 -0400
Message-ID: <5148.1560521723@sss.pgh.pa.us>
Precedence: bulk

Daniel Gustafsson <daniel@yesql.se> writes:
> Commit 3d13623d75d3206c8f009353415043a191ebab39 added the next and subid=
 fields
> to the SPITupleTable struct, but they never made it into the documentati=
on.
> While these are internal members, we already document several other inte=
rnal
> ones (with a sentence on not using them) so add these too to make the
> documentation match reality.

> Since this makes the number of internal members far outnumber the public=
 ones,
> also reword the statement about which fields can be used to try and impr=
ove
> clarity.

I wonder if we should just show the public fields in the docs?  Something
like

    typedef struct
    {
        ...
        TupleDesc   tupdesc;        /* row descriptor */
        HeapTuple  *vals;           /* rows */
        ...
    } SPITupleTable;
    =

    (The struct contains additional fields that should not be touched
    by users of SPI.)

Not wedded to that, but it would reduce the risks of future mistakes
of this same sort.

			regards, tom lane