After investigation, it turns out things aren’t quite as bad as I thought. Basically, when everything is implemented properly (GetHashCode, etc.) the documentation is correct, and the behavior is correct. But, if you try to do something like implement IEquatable all by itself, then your Equals method will never get called (this seems to be due to GetHashCode not being implemented properly). So, while the documentation is technically wrong, it’s only wrong in a fringe situation that you’d never ever want to do (if this investigation has taught me anything, it’s that IEquatable is part of a whole set of methods you should implement atomically (by convention, not by rule, unfortunately)).
Good sources on this are:
- Is there a complete IEquatable implementation reference?
- MSDN Documentation:
IEquatable<T>.Equals(T)Method - SYSK 158:
IComparable<T>vs.IEquatable<T>