Correctly document EqualValues behavior

[brackendawson]

Summary

The EqualValues docstring is ambiguous to how it actually behaves, this docstring more concisely describes the current behavior.

Changes

Update docstring for all EqualValues functions

Motivation

The ambiguity caused issues, such as #1576 where an update changed the arguably broken behaviour without breaking the ambiguous contract.

Related issues

#1576 this does not necessarily resolve the issue, nor does it preclude reverting the behavior. The aim here is only to make the documentation match the current behaviour.

[ccoVeille]

I like your proposal.