Robert Haas <robertmhaas@gmail.com> writes:
> On Tue, Jun 14, 2022 at 1:40 PM Mark Wong <markwkm@gmail.com> wrote:
>> I've created a function for each data type with the idea that an example
>> for handling a specific data type can be more easily reviewed by looking
>> in a single place.
>> I've added examples for REAL, TIMESTAMP WITHOUT TIME ZONE, and BOOLEAN
>> to try to illustrate how testlibpq3.sql and testlibpq3.c will grow if
>> this is a good way to go.
> I'm not sure that we want to let these test programs grow very large.
> In particular, I don't think we should let ourselves get sucked into
> adding an example for every data type under the sun -- if that's
> wanted, the solution is perhaps to add documentation for the binary
> formats, not hide impromptu documentation inside a test program. But
> doing this much seems OK to me.
Yeah, "hiding impromptu documentation inside a test program" is what
this looks like, and I'm not sure that's a reasonable way to go.
(1) Who's going to think to look in src/test/examples/testlibpq3.c for
documentation of binary formats?
(2) The useful details are likely to get buried in notational and
portability concerns, as I think your build failure illustrates.
(3) I bet few if any packagers install these files, so that the new
info would be unavailable to many people.
I think some new appendix in the main SGML docs would be the appropriate
place if we want to provide real documentation.
regards, tom lane