Improve Ord docs

[Voultapher]

• Makes wording more clear and re-structures some sections that can be overwhelming for someone not already in the know.
• Adds examples of how not to implement Ord, inspired by various anti-patterns found in real world code.

Many of the wording changes are inspired directly by my personal experience of being confused by the Ord docs and seeing other people get it wrong as well, especially lately having looked at a number of Ord implementations as part of #128899.

Created with help by @orlp.

r​? @workingjubilee

[rustbot]

r? @joboet

rustbot has assigned @joboet.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[workingjubilee]

@Voultapher I scanned this a bit. If you want to split it out, the diff that only concerns PartialEq and Eq already has my r+ modulo "Jubilee finds a typo on a second/third pass".

The rest will take more time to review.

[Voultapher]

@workingjubilee I have a slight preference for keeping it as one PR if that's fine for you.

[workingjubilee]

@Voultapher Understandable, then! I just wanted to extend the option.

[workingjubilee]

I got through the non-example text. The large number of whitespace-only changes are part of why this has been a bit slow to review. They are all very distracting, and some of them actually are incorrect. I haven't reviewed the examples yet.

[workingjubilee]

I will probably not be able to review the examples without these being fixed, since I will be trying to relate the examples back to prior text.

[Voultapher]

I got through the non-example text. The large number of whitespace-only changes are part of why this has been a bit slow to review. They are all very distracting, and some of them actually are incorrect. I haven't reviewed the examples yet.

In hindsight I should have split the whitespace changes out as a separate commit, sorry.

[Voultapher]

I've rebased the branch and added the requested changes as a new commit.

[Voultapher]

@workingjubilee I think the PR is waiting on review

[workingjubilee]

It is, I was working yesterday mostly on making sure backtraces are handled correctly on Android (and a lot of other platforms tbh).

[Voultapher]

No worries, please take your time. I mentioned it because the issue has the label waiting-on-author and in the past I had missed this in another PR when it was wrongly set and sat there three weeks waiting for feedback.

[workingjubilee]

Oh.
@rustbot review

[workingjubilee]

brain? earth to Jubilee?

[Voultapher]

a67d3bd is the new commit, everything else is just a rebase to not fall too far behind master.

[workingjubilee]

Thank you for this. Sorry for taking so long at points. I think this looks good!

I'm not entirely sure if providing examples of bad implementations is not more confusing, in a way? But I think we should try it and find out how people respond. We can easily remove it later if we find it has the "that sign can't stop me because I can't read!" effect, and if memory serves we currently use such "negative examples" in far more dicey situations.

And that's a relatively small part of this PR overall. This is a clear improvement throughout.

@bors r+

[bors]

📌 Commit a67d3bd has been approved by workingjubilee

It is now in the queue for this repository.

[bors]

⌛ Testing commit a67d3bd with merge 7608018...

[workingjubilee]

...bors, calm down.
@bors r-