From: Tom Lane <tgl@sss.pgh.pa.us>
To: Marcos Pegoraro <marcos@f10.com.br>
cc: Michael Paquier <michael@paquier.xyz>,
        pgsql-hackers <pgsql-hackers@postgresql.org>
Subject: Re: Missing jsonb_ ... functions on DOCs
In-reply-to: 
 <CAB-JLwb+m=gspBheMGWq9TCPqgD70K30AQ3bNxPzg3KBsym2Bg@mail.gmail.com>
References: 
 <CAB-JLwbPuNY+4Ez48TZpXg-ZuxRSJ_igsNOa-nX7jBEs97qHCQ@mail.gmail.com>
 <agE6JF1AvxKL0anI@paquier.xyz>
 <CAB-JLwb+m=gspBheMGWq9TCPqgD70K30AQ3bNxPzg3KBsym2Bg@mail.gmail.com>
Comments: In-reply-to Marcos Pegoraro <marcos@f10.com.br>
	message dated "Mon, 11 May 2026 12:07:33 -0300"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <2077213.1778512784.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Mon, 11 May 2026 11:19:44 -0400
Message-ID: <2077214.1778512784@sss.pgh.pa.us>
Archived-At: 
 <https://www.postgresql.org/message-id/2077214.1778512784%40sss.pgh.pa.us>
Precedence: bulk

Marcos Pegoraro <marcos@f10.com.br> writes:
> Em dom., 10 de mai. de 2026 às 23:08, Michael Paquier <michael@paquier.xyz>
> escreveu:
>> Well, it seems to me that the intention is that it is pointless to
>> document the functions because that the users need only to be aware of
>> the operators, and the operators are enough to manipulate the jsonb
>> blobs.  Documenting the functions would be just duplicating what we
>> already have for the operators, as listed here:
>> https://www.postgresql.org/docs/devel/functions-json.html

> A function is self explanatory, an operator is not.

We have a general policy of not documenting functions that underlie
operators, simply because doing otherwise would bloat the
documentation enormously while not adding much value.  Do we really
need documentation entries for int4pl, int48gt, float84mul,
etc etc etc?

I'm sure there are a few places where that policy wasn't followed
for some reason, but I'm loath to abandon it.  There are circa
800 entries in pg_operator (and that's just for the core code).

			regards, tom lane