Re: Re: BUG #4053: libpq documentation should express clearly, that integers are passed in network octet order

Andrew Chernow <ac(at)esilo(dot)com> writes:

> Bruce Momjian wrote:
>> Aleksej Saushev wrote:
>>> "Merlin Moncure" <mmoncure(at)gmail(dot)com> writes:
>>>
>>>> Bruce Momjian wrote:
>>>>> This brings up a good question. Exactly how do users know what format
>>>>> _binary_ is? int4 is network byte order, but what about int8, float4,
>>>>> inet?
>>>> This is exactly what libpqtypes solves. Not only do we handle
>>>> formatting of binary formats, we provide a level of protection from
>>>> internal format changes for libpq users. See the example here:
>>>> http://libpqtypes.esilo.com/. So, documentation of binary formats
>>>> (including network byte ordering) are not required.
>>> No, it is still required. There's not a single reference to libpqtypes
>>> in Postgres documentation, and libpqtypes isn't part of the distribution,
>>> if I understand it right.
>>
>> Agreed.
>
> Correct, libpqtypes is not part of the core.
>
> What we are saying is, libpqtypes solves this problem. I don't
> think docs is the solution because that just supports the idea
> of libpq apps directly handling binary formats; which makes
> changing these formats MUCH harder in future releases. Lots of
> libpq apps would be dependant on these binary formats.

Right, but that's upon developers to decide, if they're going to
support changing API. I'm pretty sure, I won't use it much anyway,
and internal documentation is good enough to fix the problem
in future.

> By all means, documenting this is probably a good idea. I just
> don't think it solves any of the interesting problems.

The easiest way to address the lack of documentation is adding
reference to libpqtypes at appropriate place. Shipping libpqtypes
along is even better.