Subject: Re: New Defects reported by Coverity Scan for PostgreSQL
To: Tom Lane <tgl@sss.pgh.pa.us>, Ning Yu <nyu@pivotal.io>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>,
 Emre Hasegeli <emre@hasegeli.com>, Pg Hackers <pgsql-hackers@postgresql.org>
References: <E1fjZo1-00019i-GG@gemulon.postgresql.org>
 <20180731172149.kdjl3xdjjtwxaj4s@alvherre.pgsql>
 <CAKmaiL2o6584gLFP=6YX-MUqmvOiT==uny+LA8z3=uAnriuzXA@mail.gmail.com>
 <26769.1533090136@sss.pgh.pa.us>
From: Tomas Vondra <tomas.vondra@2ndquadrant.com>
Message-ID: <9cc1e851-26b6-abfb-b62f-c788b14b9028@2ndquadrant.com>
Date: Wed, 1 Aug 2018 11:23:16 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101
 Thunderbird/52.5.2
MIME-Version: 1.0
In-Reply-To: <26769.1533090136@sss.pgh.pa.us>
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 08/01/2018 04:22 AM, Tom Lane wrote:
> Ning Yu <nyu@pivotal.io> writes:
>> From my point of view it's better to also put some comments for humans to
>> understand why we are passing l1 and l2 in reverse order.
> 
> The header comment for lseg_closept_lseg() is pretty far from adequate
> as well.  After studying it for awhile I think I've puzzled out the
> indeterminacies, but I shouldn't have had to.  I think it probably
> should have read
> 
>  * Closest point on line segment l2 to line segment l1
>  *
>  * This returns the minimum distance from l1 to the closest point on l2.
>  * If result is not NULL, the closest point on l2 is stored at *result.
> 
> Or perhaps I have it backwards and "l1" and "l2" need to be swapped in
> that description.  But the mere fact that there is any question about
> that means that the function is poorly documented and perhaps poorly
> named as well.  For that matter, is there a good reason why l1/l2
> have those roles and not the reverse?
> 
> While Coverity is surely operating from a shaky heuristic here, it's
> got a point.  The fact that it makes a difference which argument is
> given first means that you've got to be really careful about which
> is which, and this API spec is giving no help in that regard at all.
> 

Yeah, I agree. The comments don't make it very clear what is the API
semantics. Will fix.

regards

-- 
Tomas Vondra                  http://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services