Robert Haas wrote:
> On Wed, Jan 12, 2011 at 8:54 PM, Bruce Momjian <[email protected]> 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 <[email protected]> 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>
--
Sent via pgsql-hackers mailing list ([email protected])
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
