Re: libpq documentation cleanups (repost 3)

Robert Haas wrote:
> On Wed, Jan 12, 2011 at 1:12 PM, Bruce Momjian <bruce@momjian.us> wrote:
> >> OK, that last part seems kind of vague. ?;-) ?Can you hack up the diff
> >> to have just the changes you think are worthwhile? ?You can just remove
> >> the parts of the diff you don't like.
> >
> > Robert, here is a unified diff, which I think it easier to review for
> > single-line documention changes.
>
> Here are the parts that seem like improvements to me.

Applied.

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.

The second change is, I think, better wording.

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.

--
  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 da7b820..335b148 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</> even when <symbol>NULL</> is returned by
+       the function; this indicates an out-of-memory situation.)
       </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>
@@ -3162,6 +3162,11 @@ Oid PQoidValue(const PGresult *res);

      <listitem>
       <para>
+       This function is deprecated in favor of
+       <function>PQoidValue</function>.  It is not thread-safe.
+      </para>
+
+      <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
@@ -3175,10 +3180,6 @@ 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>