Re: Lack of docs for libpq C Library

Hello, Bruce.

You wrote:

BM> Alvaro Herrera wrote:
>> Bruce Momjian wrote:
>> > Pavel Golub wrote:
>> > > Hello, pgsql-docs.
>> > >
>> > > I noticed that some exported functions are not documented in the
>> > > Chapter 30. However, there are some info about them in other chapters,
>> > > e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic
>> > > Character Set Conversion Between Server and Client".
>> >
>> > Though they are exported, the are more for internal use, e.g. psql,
>> > rather than something we want people using --- they can change from
>> > release to release.
>>
>> I disagree. I think PQinitSSL is meant to be called from the
>> application, for example. Same with PQsetClientEncoding. And the

BM> I see PQinitSSL and PQsetClientEncoding mentioned in the documentation;
BM> is it lacking enough detail?

Well they are. But in wrong place. I was using 'SET client_encoding TO
xxx' SQL a long time. And then I found PQsetClientEncoding in wrong
place.

Then PQmblen function. I beleive it means PQMultiByteLength? If so, it
would be very usefull for me.

>> PQExpBuffer stuff is all very useful, and years ago when I wrote an app
>> to use it it annoyed me that there were no docs on it. (Back then, I
>> didn't realize I could have complained about it or written the docs
>> myself).

BM> True but we don't guarantee the API of many of these functions like we
BM> do the documented ones.

You may state in that these functions are internal and nobody is
recommended using them. At least developers haven't to try to guess
what they mean and create some kind of Colossus with feet of clay based on
these guesses.

BM> ---------------------------------------------------------------------------

>>
>>
>> > ---------------------------------------------------------------------------
>> >
>> >
>> > >
>> > > This is the list of exported functions without docs:
>> > > ================
>> > > PQclientEncoding
>> > > PQsetClientEncoding
>> > > PQconninfoFree
>> > > PQdsplen
>> > > PQenv2encoding
>> > > PQinitSSL
>> > > PQmblen
>> > > PQregisterThreadLock
>> > > appendPQExpBuffer
>> > > appendPQExpBufferChar
>> > > appendPQExpBufferStr
>> > > createPQExpBuffer
>> > > destroyPQExpBuffer
>> > > enlargePQExpBuffer
>> > > initPQExpBuffer
>> > > appendBinaryPQExpBuffer
>> > > pg_char_to_encoding
>> > > pg_encoding_to_char
>> > > pg_utf_mblen
>> > > pg_valid_server_encoding
>> > > pgresStatus
>> > > pqsignal
>> > > printfPQExpBuffer
>> > > resetPQExpBuffer
>> > > termPQExpBuffer
>>
>>
>> --
>> Alvaro Herrera http://www.CommandPrompt.com/
>> The PostgreSQL Company - Command Prompt, Inc.
>>
>> ---------------------------(end of broadcast)---------------------------
>> TIP 9: In versions below 8.0, the planner will ignore your desire to
>> choose an index scan if your joining column's datatypes do not
>> match

--
With best wishes,
Pavel mailto:pavel(at)gf(dot)microolap(dot)com