Consider changing naming convention to indicate squared distances

[Andlon]

Just spent some time scratching my head with CollisionConstraints::compute_minimum_distance. The documentation says it returns the minimum distance, but I found this in the implementation:

// NOTE: Actually distance squared

I realize that you're basically working with squared distances throughout (although for an outside user it is not clear if this holds in all cases), but it's still very confusing that "distance", which is a very unambiguously defined term in my opinion, actually means "squared distance". In my opinion, it would reduce confusion a lot for the new users and possible contributors if squared distances were always marked as such, e.g. by using naming like compute_squared_distance, compute_distance2 or similar.

(I labeled this as "bug" as, if you take the documentation and function names at their face value, what is returned is not what the naming suggests)

[zfergus]

I see the confusion. Definitely at the very least the documentation for the compute_minimum_distance function needs to be updated to state the returned value is a squared distance.

I originally choose not to put the word squared in the function names to keep them short and concise, and as you said distance in the toolkit is unanimously referring to a squared distance. However, I agree this can be confusing. Let me think about how to best proceed.

[Andlon]

Actually, one small counterpoint to the point about squared distances being unanimous: Some parameters are actually not squared, such as dhat and dmin, I believe.

[zfergus]

Yes, you are right dhat and dmin are unsquared.