Re: SPITupleTable members missing in docs

From: Fabien COELHO <coelho(at)cri(dot)ensmp(dot)fr>
To: Daniel Gustafsson <daniel(at)yesql(dot)se>
Cc: pgsql-docs(at)lists(dot)postgresql(dot)org, Michael Paquier <michael(at)paquier(dot)xyz>, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>
Subject: Re: SPITupleTable members missing in docs
Date: 2019-07-12 14:56:31
Message-ID: alpine.DEB.2.21.1907121649180.8895@lancre
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs


Hello Daniel,

> 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.

Patch applies cleanly, doc build ok.

To take into account Tom's comment, I'd suggest a middle ground by
commenting a public and private part explicitely in the struct, something
like:

typedef struct {
/* PUBLIC members to be used by callers ... */
...
...
/* PRIVATE members, not intended for external usage ... */
...
} ... ;

Another option would be to use some python-like naming convention on such
members, eg with a leading underline character.

Even if it is redundant with the paragraph below, it would make things
visually clear as well.

Note: I'm probaly not a member of the pgdoc list, so the delivery may fail
there.

--
Fabien.

In response to

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Tom Lane 2019-07-12 15:04:39 Re: SPITupleTable members missing in docs
Previous Message Liudmila Mantrova 2019-07-12 09:35:49 Re: misc doc fixes for REL_12_STABLE