On Fri, Jan 20, 2023 at 12:58 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I don't mind if you write something like
>
> A float4 value is a 4-byte IEEE single-precision floating point
> number. It is transmitted in network byte order, so you must
> convert to local byte order. (C users can do this portably
> using the standard ntohl() function.)
>
> but I'm not sure an example is worth more than such a parenthetical
> comment. Perhaps others disagree, though.
I don't disagree with that.
I do think that when you suggested documenting this rather than just
adding some examples, you moved the goalposts a long way. If we're
going to add this to the documentation, it probably ought to cover
every data type we ship. Overall, I think that would be a better
result than just adding a few examples for the most common data types
to testlibpq*.c, but it's also substantially more work. I do agree
with you that if we're going to document this, as opposed to provide
examples, then a narrative style is more appropriate than a whole
bunch of small sample programs; maintaining working code in the
documentation seems like an annoying amount of maintenance and is
probably not the most efficient way to communicate useful information.
--
Robert Haas
EDB: http://www.enterprisedb.com