libpq documentation cleanups (repost 3)

Started by Bruce Momjianalmost 15 years ago10 messages
#1Bruce Momjian
bruce@momjian.us
1 attachment(s)

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

http://wiki.postgresql.org/wiki/Documentation_Proofreading

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Attachments:

/pgpatches/libpq.gzapplication/x-gzipDownload
#2Robert Haas
robertmhaas@gmail.com
In reply to: Bruce Momjian (#1)
Re: libpq documentation cleanups (repost 3)

On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

       http://wiki.postgresql.org/wiki/Documentation_Proofreading

I don't think changing "see below" to "refer below" or "call" to
"execute" is an improvement; even if we did that uniformly throughout
our documentation, surely future editors are going to reuse those
phrasings.

A lot of these other changes look pretty dubious too, although some
seem worthwhile.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

#3Dmitriy Igrishin
dmitigr@gmail.com
In reply to: Robert Haas (#2)
Re: libpq documentation cleanups (repost 3)

2011/1/12 Robert Haas <robertmhaas@gmail.com>

On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

http://wiki.postgresql.org/wiki/Documentation_Proofreading

I don't think changing "see below" to "refer below" or "call" to
"execute" is an improvement; even if we did that uniformly throughout
our documentation, surely future editors are going to reuse those
phrasings.

A lot of these other changes look pretty dubious too, although some
seem worthwhile.

I propose to change "backend server" to "backend" or "server.
Robert, you mentioned that "backend server" phrase is suggest
interchangeability of "backend" or "server" but there is no term
"backend server".

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers

--
// Dmitriy.

#4Bruce Momjian
bruce@momjian.us
In reply to: Robert Haas (#2)
Re: libpq documentation cleanups (repost 3)

Robert Haas wrote:

On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

? ? ? ?http://wiki.postgresql.org/wiki/Documentation_Proofreading

I don't think changing "see below" to "refer below" or "call" to
"execute" is an improvement; even if we did that uniformly throughout
our documentation, surely future editors are going to reuse those
phrasings.

A lot of these other changes look pretty dubious too, although some
seem worthwhile.

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.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

#5Bruce Momjian
bruce@momjian.us
In reply to: Bruce Momjian (#4)
1 attachment(s)
Re: libpq documentation cleanups (repost 3)

Bruce Momjian wrote:

Robert Haas wrote:

On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

? ? ? ?http://wiki.postgresql.org/wiki/Documentation_Proofreading

I don't think changing "see below" to "refer below" or "call" to
"execute" is an improvement; even if we did that uniformly throughout
our documentation, surely future editors are going to reuse those
phrasings.

A lot of these other changes look pretty dubious too, although some
seem worthwhile.

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.

--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ It's impossible for everything to be true. +

Attachments:

/pgpatches/libpq.gzapplication/x-gzipDownload
���-Mlibpq�<iW�F���W��oL�
f'M�!��p�
����>e�l+�%�J����]j�,��er��Id�\���V���H�z��r#��
]��i��������p��7I�'q�=�>����:8���Vb���������-��f}}}9���]���w��b���������������\�����|rw����GeR���"��4y�E�t&�d�*|��D�JGE2+�B�BI}��O��3YH�)�@L�X	]�fyQj!ETS��J������P�����D�)����E����+�
5i������[\lONc������}q���4������U��}�T��BN�D�I6��1��}��'^��D����C��9��"�Y����������wE'��B��&�'Yc��U1���R�D���x��C8��������T1Z�`D$+��(U,WS�7���E,,U�����_c�}<�)<����@@�����6�-x`�c�����{4��kiz]����y�*T� B�
q?QZy�P��(IS �pN�?���L���d���0���S^��s0^j�d8��j�cc�?<������v���9�<�b��(Z��]�,>���_�<��7���2��r���R������?�E���v�A����	�3�4�Y��T#>���"���a�a��J��y?^�4�bB�*_`�3���|*��\��t���W//�6�=�$#a�E!����^��:!M�ezl����3�&
�x�d����Gh?X�����8T��O @~�V����_�d_6NP�'(�p���7������b��R&Y����Fz��1K�?�8�L?���H�e>N���cV�n�� �
���R�'P�����0({��
��)�����N�B� A�MG\Y�`�����l���D�L��X��5yW��d��Y����������&`����O�0�yF�X��z�"'���<���>��8�1k�L�C@x6�H�8K�T�w��*.>� ��e1�NHZb��jo�_+X���6�AH��6[���l�u��a�\��O
�,Z�X����
��j��;q��?"�����T�G�����(�!��+�P�Q�Q��:�z���o��d��q��Ad�S0��>��X��&6����8`�����H���f���l\��ox�-�}�2�/3�����f���$�G���A�p���
P`�e�����|H@pk]Vd����w{��<����,����E��gH��\I����V�4��('�����@����Xp�
M+����9�xI��z(��@��o����><���"����qN1>���"�{�$4��?�g)� ��;G2*�l>=���D�#�.\�A`Q�������9��v����$ZW~KxO�1ds/:=i�+���x�k���$+4����N��%�:�`����J�����X����#����P�&O!AC�QV�~>S�	^�Xq��c��,���ZbPD5AL]�� 9%��uor�{Qv:o�
5Ke�0M:�P>�G�����v����?=@�I��V�_d� �%
Ey��Rc��)OA��H�Fp��(�u�@�x�)��#$�'�#��
�A����
R�?������
��D����Y1�A�A�?�����	���*|`'��6�>�K��$[�_g*�R>%Z�m�M�$�$D��C��FM$���� �2�>�Y���
h���p�k�����������O?������
�$4#�K�.�,�
L�,���0�[x�
�`��
���&c��9���#e�)��@N4Z�,R��}��$�BK]�X��|��!���r��5�C�
C��6�k�x�r��3���?)O$Y����i��/��4%������O7���W�|�=?9�c (�2���IF���2g�:,A�Af h&�D�c�U
�u����_>�	t2MR������k���h�X�W%�=��<ghA��|5c���Di�+QZ����^�����T��Q(�d��������dv����c����P
�yJ��������]�;DVB�J��/2���;eF
��> m]V��3��z�p���6�:�%d��	$}qU����IO����0��\�rL�&
���i��j��� vM�qp��96Gs����Nv=���w<�
`����?����{b8�j�E��bN��VY�X|��MH���25���(��'�2*1�k�]�������M=9�lh�8M����tE�7�F�:�\Q"�'�����Y4��$Ql#`���P�����6�+KP�X�LX�R���������������7�~S��4W��X��_�����B���ZS����04��M@X�D�I������p����:�)<��SPy�G����kz/�����sEIe�6}���!�w�����V����W�!�+][<PE1���[��	d�G�4��������Zx����4�wS����qb�|x�������1%�Q[@`�m��#�-:�(���]���eh�=f��A���9Dde67��!��f����oQ/{���o+����]$6s���}�����=����lv��@�*����Z���iJ��o��ya�X=�R��g��F�p���~xg�����(uc�pr���U=�������	��m�t�Z�yU��Qo��y��W��%�������
�]�1�a��3��M4�p�
�!����\B��W�d(������ 3��6�s���Mb��o�tg,��,�Z�&j,��,D�b�8bjX�^c�X�UA��N[�/C�_��z[5}�s�G��9�7���Z�|pe��el�W��~la!�Ab�|�
`��y�Gy�/H*�HK��A���������1�$$6�I�C��:C��t�c[��2�B�|)j�s�kf��]u���k�XS�A��%:[�M�JK�������fx$���������o|L �\�jHjv"�]��l�4;�L�Z����m���
��a�5��J��r� �ID	��guY/���4>7\����R�� ���Lg�����,���m�;��r �*)]�n��|�n�i��^����='�/��sP-qM#��In
c(��������N�CNt9kz���=/��\��Iz?CA��V�1��*J���8'>�����r6���T>!�����}���y�(~]������k���C]$��g��1{o�
����reW
l�����b�e	�/ERL��H��NB�^�r0>�<T�*/������Zx��d������x��_%���7��X�2���������H���M����\�4/���y�
�P2����4!������,J�XQ������G���
 �4�d\G�R5�1o���R���a���fc��V�u%X�n�>\Wn�S3x���h��.��=3��j��C?�F�A������)��N��:1���%���U�`
�>V��d�P�^��1�d���wX���A��i�3
�xCwh��"�� 9�b�����������Wm<QkD�;�<�������{����A�
=�+1}b��KX�����B�q,�Q� My2D[�%�zX�G��`����{HL��d�$�3�N����`n�������Jx�?��v����-�A+FQ��T�YLc��hT#{�����3���H�zI
�1��P�?�C�7��N�xh�z��9E�������8���I-�C��fb�fUe��������O�������c��O�Q?������ �/�*��ir�S��z?��"<�q}�[-S�+���I���+G
l�
�Z���n�1�������8��&��T�14S���v��_-������
h<M���xj����gI��E��\��J/_��
Ja��Q(��k����4
�*K��7V��!jH<at2|d>�������
����pz�����
�r�7T�-�q5sK&�8	�Q](���2�a��p����u�`F�j&���%�D��1�3	�1�~`�������x�w�-x�yQ��k&�x�*ak��J4EC0:�<��T���NWb������;�d>��1I��{;�]�~�4&��n�#!����@��:��hqs/������`��E_�/����2rl��� �p�@�jj4�:,&�A��P��[�jQ^D����5&8��
`�����rN���"��!�����)�Z;R���k�t^_���(l��v���s���8���ExVM3�RW�uqz�}|��%��/unV���etZO���;����K�f���01	�,�Vi����,�,��-�)wy��F�
�*d��/����-��u8������/c���D��u[��o��1��a��
'����C+"j#|2
N
^��-&�@i2�s�yn��$�Yn������{���{��`��������rZ��q��7A!%)6�]Z�R�c8h������N
��Z/��g���|��_��^�o��c���t�{��:t�B�	LV�=Zw�/����uPk�UeX�����	�"�Hc�\��KP��x�u`9�L�0����	K�m���5l��8��(����f�
'�I��uR���=[�>'f T2}FiftCSm���b;��!g[��I�qai[�3��*�'����i���l����������\�~�����8�|Gq�"��UjDP{�q����$7�$����0b�
��2�������!�hS*/�]F����[k��z���I�(����i9R�v���D=���E&3p���H�"��	5��(��.@��.�|���N�.���o2.28um���dD%�L�[�l���G*>��{0H3f��.��������	�k�9<�7����������b����k�c�z�L��E���`�rS8����l4�%����v�D���
U�['j�,����
�x"����$&�Z��4��P���,��	7�y����G7�M���:��Gz6o��6��
?n�en �At��������5���Y�&��~:�r�I<���:����S��M��r�v��p^�(/5����{�bgwg�l�0
��<�g�3�)�#���`�X���&q������
J9�MD�.�^��
��h�g�G"U�\�h�<�T+k�����a@�F�5�y�O��Q��M�[V��i����:0��+5m�](����/_�����O�p�����@��P�h^O�,��v

�_�����><��#T����n����n�gj�`F�D=(�y@7�gu3����6w��)�	��/�W�z@�r��Ic�~~�v��4?D�����(�����jW{�[������d;��r����2��>�F����,]��;��O��e�@?a?��N>�ND����k���(_`n����+KQ�`����I�83;A9=�\��:��������"x�m�'�yf�	�_i) v�.u[U��i����K�t�l�����&�A
�����h�v<)�����~�'�����D��	P����n`����&�MJ>�]��x�����8�5�m��-��~�/j����6N���������q��fSs�8�q[��j{c�.r�hc�=�cLG��S�B2��������G����;�\�5vb���q_�N������b�)M�H4�n�P���}N�.��s�����!��C
�q�c�7?�Q��iCje��
�����~�;�O6�3�Cq����{��~���"����3�v��5��B:�f	������^��e��������@*Mgo��!��dp�=����nm���2P'����[��;�<�^�h���	��*���?}�^�E��DvL��7(���s��9Cl��yA>��l�
��2\��Oy��r�;`���������}�o{�RJ>|/���,�k��cJ7SE�W���Es����
�j�����
*�����%�"k�'Q�5��MZ�Tx���I���A�����o�����MftT
#6Robert Haas
robertmhaas@gmail.com
In reply to: Bruce Momjian (#5)
1 attachment(s)
Re: libpq documentation cleanups (repost 3)

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.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Attachments:

libpq-docs.patchapplication/octet-stream; name=libpq-docs.patchDownload
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index da7b820..58e593d 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -397,8 +397,8 @@ PGconn *PQconnectdbParams(const char **keywords, const char **values, int expand
              <row>
               <entry><literal>verify-ca</></entry>
               <entry>only try an <acronym>SSL</> connection, and verify that
-              the server certificate is issued by a trusted <acronym>CA</>
-              </entry>
+              the server certificate is issued by a trusted certificate
+              authority (<acronym>CA</>)</entry>
              </row>
 
              <row>
@@ -791,8 +791,8 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 
       <para>
        At any time during connection, the status of the connection can be
-       checked by calling <function>PQstatus</>. If this gives <symbol>CONNECTION_BAD</>, then the
-       connection procedure has failed; if it gives <function>CONNECTION_OK</>, then the
+       checked by calling <function>PQstatus</>. If this call returns <symbol>CONNECTION_BAD</>, then the
+       connection procedure has failed; if the call returns <function>CONNECTION_OK</>, then the
        connection is ready.  Both of these states are equally detectable
        from the return value of <function>PQconnectPoll</>, described above. Other states might also occur
        during (and only during) an asynchronous connection procedure. These
@@ -956,7 +956,7 @@ PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg);
       <para>
        Parses a connection string and returns the resulting options as an
        array; or returns <symbol>NULL</> if there is a problem with the connection
-       string.  This can be used to determine
+       string.  This function can be used to extract
        the <function>PQconnectdb</function> options in the provided
        connection string.  The return value points to an array of
        <structname>PQconninfoOption</structname> structures, which ends
@@ -1486,9 +1486,10 @@ const char *PQparameterStatus(const PGconn *conn, const char *paramName);
 <synopsis>
 int PQprotocolVersion(const PGconn *conn);
 </synopsis>
-       Applications might wish to use this to determine whether certain
+       Applications might wish to use this function to determine whether certain
        features are supported.  Currently, the possible values are 2 (2.0
-       protocol), 3 (3.0 protocol), or zero (connection bad).  This will
+       protocol), 3 (3.0 protocol), or zero (connection bad).  The
+       protocol version will
        not change after connection startup is complete, but it could
        theoretically change during a connection reset.  The 3.0 protocol
        will normally be used when communicating with
@@ -1513,7 +1514,7 @@ int PQprotocolVersion(const PGconn *conn);
 <synopsis>
 int PQserverVersion(const PGconn *conn);
 </synopsis>
-       Applications might use this to determine the version of the database
+       Applications might use this function to determine the version of the database
        server they are connected to. The number is formed by converting
        the major, minor, and revision numbers into two-decimal-digit
        numbers and appending them together. For example, version 8.1.5
@@ -1547,7 +1548,7 @@ char *PQerrorMessage(const PGconn *conn);
        Nearly all <application>libpq</> functions will set a message for
        <function>PQerrorMessage</function> if they fail.  Note that by
        <application>libpq</application> convention, a nonempty
-       <function>PQerrorMessage</function> result can be multiple lines,
+       <function>PQerrorMessage</function> result can consist of multiple lines,
        and will include a trailing newline. The caller should not free
        the result directly. It will be freed when the associated
        <structname>PGconn</> handle is passed to
@@ -1717,8 +1718,8 @@ PGresult *PQexec(PGconn *conn, const char *command);
      </varlistentry>
     </variablelist>
 
-    It is allowed to include multiple SQL commands (separated by semicolons)
-    in the command string.  Multiple queries sent in a single
+    The command string can include multiple SQL commands
+    (separated by semicolons).  Multiple queries sent in a single
     <function>PQexec</> call are processed in a single transaction, unless
     there are explicit <command>BEGIN</command>/<command>COMMIT</command>
     commands included in the query string to divide it into multiple
@@ -4142,7 +4143,7 @@ int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
       <para>
        The return value is 1 if the cancel request was successfully
        dispatched and 0 if not.  If not, <parameter>errbuf</> is filled
-       with an error message explaining why not.  <parameter>errbuf</>
+       with an explanatory error message.  <parameter>errbuf</>
        must be a char array of size <parameter>errbufsize</> (the
        recommended size is 256 bytes).
       </para>
#7Peter Eisentraut
peter_e@gmx.net
In reply to: Robert Haas (#2)
Re: libpq documentation cleanups (repost 3)

On ons, 2011-01-12 at 12:04 -0500, Robert Haas wrote:

On Wed, Jan 12, 2011 at 11:53 AM, Bruce Momjian <bruce@momjian.us> wrote:

The attached patch is a collection of libpq documentation cleanups
recommended in a list of changes emailed to me by Leslie S Satenstein.

Leslie found a number of places our libpq documentation that were unclear
or awkward, and this diff generated by me attempts to address them.

I have already updated the documentation proofreading wiki:

http://wiki.postgresql.org/wiki/Documentation_Proofreading

I don't think changing "see below" to "refer below" or "call" to
"execute" is an improvement; even if we did that uniformly throughout
our documentation, surely future editors are going to reuse those
phrasings.

Agreed.

A lot of these other changes look pretty dubious too, although some
seem worthwhile.

Agreed. :-/

#8Bruce Momjian
bruce@momjian.us
In reply to: Robert Haas (#6)
1 attachment(s)
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. +

Attachments:

/pgpatches/libpq_v2text/x-diffDownload
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>
#9Robert Haas
robertmhaas@gmail.com
In reply to: Bruce Momjian (#8)
Re: libpq documentation cleanups (repost 3)

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.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

#10Bruce Momjian
bruce@momjian.us
In reply to: Robert Haas (#9)
1 attachment(s)
Re: libpq documentation cleanups (repost 3)

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. +

Attachments:

/pgpatches/libpq_v2text/x-diffDownload
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>