Re: libpq documentation cleanups (repost 3)
От | Bruce Momjian |
---|---|
Тема | Re: libpq documentation cleanups (repost 3) |
Дата | |
Msg-id | 201101131709.p0DH99P14490@momjian.us обсуждение исходный текст |
Ответ на | Re: libpq documentation cleanups (repost 3) (Robert Haas <robertmhaas@gmail.com>) |
Список | pgsql-hackers |
Robert Haas wrote: > On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <bruce@momjian.us> wrote: > > I am also attaching a few more of Leslie's changes that I think are > > useful. ?The first clarifies a confusion Leslie had about the fact that > > "return" is referencing the return value of the function and not the > > value returned in the pointer. > > Hmm. Well, if that's the confusion, I don't think inserting the words > "by the function" is the right way to fix it - it certainly isn't > returned by anything else. You could change it to say "It is also > possible for *errmsg to be NULL even when the return value is also > NULL; this indicates..." > > > The second change is, I think, better wording. > > OK. > > > The third moves the "deprecated" text to the start of the function > > description. ?Leslie pointed out that that is how we do it for other > > libpq functions, so we should move it for consistency. > > That seems to me to read pretty awkwardly. You could perhaps strike > the chunk and the whole first paragraph and simply write "PQoidStatus > is an older, deprecated version of PQoidValue. It returns its result > as a character string rather than an Oid, and is not thread-safe." and > then cut directly to the synopsis. That would be consistent with what > we've done elsewhere; moving just that one sentence is not. OK, I have made the adjustments you mentioned with my own wording (attached and applied). Let me know of any more needed adjustments. Thanks. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + It's impossible for everything to be true. + diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 58e593d..fe661b8 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -972,8 +972,8 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); If <literal>errmsg</> is not <symbol>NULL</>, then <literal>*errmsg</> is set to <symbol>NULL</> on success, else to a <function>malloc</>'d error string explaining the problem. (It is also possible for <literal>*errmsg</> to be - set to <symbol>NULL</> even when <symbol>NULL</> is returned; this indicates an out-of-memory - situation.) + set to <symbol>NULL</> and the function to return <symbol>NULL</>; + this indicates an out-of-memory condition.) </para> <para> @@ -1352,7 +1352,7 @@ ConnStatusType PQstatus(const PGconn *conn); <para> See the entry for <function>PQconnectStartParams</>, <function>PQconnectStart</> and <function>PQconnectPoll</> with regards to other status codes that - might be seen. + might be returned. </para> </listitem> </varlistentry> @@ -3163,23 +3163,15 @@ Oid PQoidValue(const PGresult *res); <listitem> <para> - Returns a string with the OID of the inserted row, if the - <acronym>SQL</acronym> command was an <command>INSERT</command> - that inserted exactly one row, or a <command>EXECUTE</command> of - a prepared statement consisting of a suitable - <command>INSERT</command>. (The string will be <literal>0</> if - the <command>INSERT</command> did not insert exactly one row, or - if the target table does not have OIDs.) If the command was not - an <command>INSERT</command>, returns an empty string. + This function is deprecated in favor of + <function>PQoidValue</function> and is not thread-safe. + It returns a string with the OID of the inserted row, while + <function>PQoidValue</function> returns the OID value. <synopsis> char *PQoidStatus(const PGresult *res); </synopsis> </para> - <para> - This function is deprecated in favor of - <function>PQoidValue</function>. It is not thread-safe. - </para> </listitem> </varlistentry> </variablelist>
В списке pgsql-hackers по дате отправления: