Re: PQHost() undefined behavior if connecting string contains both host and hostaddr types

On Tue, Mar 27, 2018 at 11:43:27AM +1100, Haribabu Kommi wrote:
> Patch attached with the above behavior along with other comments from
> upthread.

Thanks for the updated version.

The function changes look logically good to me.

+ <para>
+ The <function>PQhost</function> function returns NULL when the
+ input conn parameter is NULL or an empty string if conn cannot be evaluated.
+ Applications of this function must carefully evaluate the return value.
+ </para>
+
+ <note>
+ <para>
+ when both <literal>host</literal> and <literal>hostaddr</literal>
+ parameters are specified in the connection string, the connection
+ <literal>host</literal> parameter is returned.
+ </para>
Some nitpicking about the documentation changes:
- NULL needs to use the markup <symbol>.
- conn should use the markup <parameter>. As the docs describe a value
of the input parameter, we cannot talk about "the connection" either in
those cases.
- "Applications of this function must carefully evaluate the return
value" is rather vague, so I would append to the end "depending on the
state of the connection involved."
The same applies to PQport() for consistency.

Perhaps the documentation should mention as well that making the
difference between those different values is particularly relevant when
using multiple-value strings? I would rather add one paragraph on the
matter than nothing. I really think that we have been lacking clarity
in the documentation for those APIs for too long, and people always
argue about what they should do. If we have a base documented, then we
can more easily argue for the future as well, and things are clear to
the user.
--
Michael