Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 11.5 \(3445.9.1\))
Subject: Re: SPITupleTable members missing in docs
From: Daniel Gustafsson <daniel@yesql.se>
In-Reply-To: <5148.1560521723@sss.pgh.pa.us>
Date: Fri, 14 Jun 2019 16:40:51 +0200
Cc: pgsql-docs@lists.postgresql.org
Content-Transfer-Encoding: quoted-printable
Message-Id: <FF46808A-4B7B-4B48-B265-0707991C6970@yesql.se>
References: <0D19F836-B743-4340-B6A2-F148CA3DD1F0@yesql.se>
 <5148.1560521723@sss.pgh.pa.us>
To: Tom Lane <tgl@sss.pgh.pa.us>
Precedence: bulk

> On 14 Jun 2019, at 16:15, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>=20
> 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 =
documentation.
>> While these are internal members, we already document several other =
internal
>> ones (with a sentence on not using them) so add these too to make the
>> documentation match reality.
>=20
>> 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 =
improve
>> clarity.
>=20
> I wonder if we should just show the public fields in the docs?  =
Something
> like
>=20
>    typedef struct
>    {
>        ...
>        TupleDesc   tupdesc;        /* row descriptor */
>        HeapTuple  *vals;           /* rows */
>        ...
>    } SPITupleTable;
>=20
>    (The struct contains additional fields that should not be touched
>    by users of SPI.)
>=20
> Not wedded to that, but it would reduce the risks of future mistakes
> of this same sort.

Yeah, that=E2=80=99s clearly an alternative.  If we go down this route, =
then perhaps
the docs should be swept for other instances (if any) and handle them =
all to
keep things consistent? (and yes, I volunteer if we want to opt for =
that.)

cheers ./daniel=