Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve Ord docs #129003

Merged
merged 5 commits into from
Sep 29, 2024
Merged

Improve Ord docs #129003

merged 5 commits into from
Sep 29, 2024

Conversation

Voultapher
Copy link
Contributor

@Voultapher Voultapher commented Aug 12, 2024 •
edited
Loading

  • 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
Copy link
Collaborator

rustbot commented Aug 12, 2024

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

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Aug 12, 2024
@tgross35 tgross35 mentioned this pull request Aug 16, 2024
Open
@joboet joboet assigned workingjubilee and unassigned joboet Aug 19, 2024
@workingjubilee
Copy link
Member

@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
Copy link
Contributor Author

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

@workingjubilee
Copy link
Member

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

@Voultapher Voultapher mentioned this pull request Aug 25, 2024
Closed
workingjubilee
workingjubilee requested changes Aug 25, 2024
View reviewed changes
Copy link
Member

@workingjubilee workingjubilee left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
library/core/src/cmp.rs Show resolved Hide resolved
library/core/src/cmp.rs Outdated Show resolved Hide resolved
@rustbot rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 25, 2024
@workingjubilee
Copy link
Member

workingjubilee commented Aug 25, 2024 •
edited
Loading

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
Copy link
Contributor Author

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
Copy link
Contributor Author

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

schuetzm
schuetzm reviewed Aug 27, 2024
View reviewed changes
library/core/src/cmp.rs Outdated Show resolved Hide resolved
@Voultapher
Copy link
Contributor Author

@workingjubilee I think the PR is waiting on review

@workingjubilee
Copy link
Member

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

@Voultapher
Copy link
Contributor Author

Voultapher commented Aug 29, 2024 •
edited
Loading

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
Copy link
Member

Oh.
@rustbot review

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 29, 2024
@workingjubilee
Copy link
Member

brain? earth to Jubilee?

@Voultapher
Improve Ord docs
a2c82f9 
- Makes wording more clear and re-structures some
  sections that can be overwhelming for some not
  already in the know.
- Adds examples of how *not* to implement Ord,
  inspired by various anti-patterns found in real
  world code.
@Voultapher
Fix mistake in example
d944931
@Voultapher
Copy link
Contributor Author

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

@workingjubilee
Copy link
Member

workingjubilee commented Sep 29, 2024 •
edited
Loading

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
Copy link
Contributor

bors commented Sep 29, 2024

📌 Commit a67d3bd has been approved by workingjubilee

It is now in the queue for this repository.

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 29, 2024
@matthiaskrgr matthiaskrgr mentioned this pull request Sep 29, 2024
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Sep 29, 2024
@bors
Auto merge of rust-lang#131029 - matthiaskrgr:rollup-rh66wir, r=matth…
7608018 
…iaskrgr

Rollup of 4 pull requests

Successful merges:

 - rust-lang#123932 (restate GlobalAlloc method safety preconditions in terms of what the caller has to do for greater clarity)
 - rust-lang#129003 (Improve Ord docs)
 - rust-lang#130972 (stabilize const_cell_into_inner)
 - rust-lang#130990 (try to get rid of mir::Const::normalize)

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit c1e54cf into rust-lang:master Sep 29, 2024
6 checks passed
@rustbot rustbot added this to the 1.83.0 milestone Sep 29, 2024
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Sep 29, 2024
@rust-timer
Unrolled build for rust-lang#129003
7004213 
Rollup merge of rust-lang#129003 - Voultapher:improve-ord-docs, r=workingjubilee

Improve Ord docs

- 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 rust-lang#128899.

Created with help by `@orlp.`

r​? `@workingjubilee`
@bors
Copy link
Contributor

bors commented Sep 29, 2024

⌛ Testing commit a67d3bd with merge 7608018...

@workingjubilee
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@schuetzm schuetzm schuetzm left review comments

@PatchMixolydic PatchMixolydic PatchMixolydic left review comments

@workingjubilee workingjubilee workingjubilee requested changes

Assignees

@workingjubilee workingjubilee

Labels
S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.83.0
Development

Successfully merging this pull request may close these issues.
7 participants
@Voultapher @rustbot @workingjubilee @bors @schuetzm @PatchMixolydic @joboet