ValueTuple.CompareTo documentation is wrong

[int19h]

https://docs.microsoft.com/en-us/dotnet/api/system.valuetuple.compareto

The current description of the method is:

Returns 0 if other is a ValueTuple instance and 1 if other is null.

This is obviously wrong for many reasons, starting with the fact that other cannot be null since it's a value type. And, of course, tuples compare according to the values of their elements, not just type. Furthermore, this method - like IComparable.CompareTo, to which it corresponds - returns -1, 0 or 1 depending on the relative ordering, not just 0 and 1.

Reading the source code of ValueTuple shows that it does what you'd expect it to do, namely, lexicographical ordering, comparing the elements left to right using the default comparer, until it finds the first pair that is not equal; the result of that comparison is then returned. If all elements are equal, then tuples are considered equal.

However, it's not clear whether this is an explicit design guarantee, or just an artifact of implementation. By implementing IComparable, tuples commit to providing some total ordering, but not necessarily this way of doing it. Given the nature of tuples, this common sense implementation should probably be the guarantee - it's useful in many scenarios, such as e.g. comparing coordinates, versions, and any other case where lexicographical comparison is appropriate.

But as it is an API design question, the maintainers of the component should clarify the intent. @stephentoub?

[rpetrusha]

Thanks for noticing the error and reporting, @int19h. The documentation is indeed incorrect, although actually ValueTuple.CompareTo (the comparison of two 0-tuples) always returns 0. I've opened PR #2976 to correct the documentation.

[int19h]

Ah, I see. I suppose I expected to see the general rule for how CompareTo works for tuples of any size on that page.

Looking at pages for 2-tuple etc, I see that they say that there's a relative position, which they define in terms of "this instance precedes/follows other in sort order". But they still don't define what that sort order actually is.

[int19h]

E.g. https://docs.microsoft.com/en-us/dotnet/api/system.valuetuple-2.compareto

[rpetrusha]

@int19h, you're certainly correct that the documentation is lacking in detail about the comparison. I'll open an issue to add it to the documentation.