Clarify documentation labelling and definitions for std::collections

[root-goblin]

Page affected: https://doc.rust-lang.org/std/collections/index.html#performance

Changes:

• bulleted conventions
• expanded definitions on terms used
• more accessible language
• more informative headings

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @workingjubilee (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[workingjubilee]

This is not a subsection of the preceding section. These are not statements about conventions, these are factual statements about the collections. The introduction of sectioning here does not seem to add anything to this part of the documentation.

[root-goblin]

I added subsections here originally to act as 'definition' headers, but reducing header noise is also pretty reasonable

[workingjubilee]

Yeah, I did see what you were trying to do! It just didn't seem to pan out quite like you intended, imo.

[workingjubilee]

This part of the change seems fine, so I think the conventions should just be given the list without making them into a distinct subsection.

[workingjubilee]

The bots want you to fix the trailing whitespace, it seems.

[workingjubilee]

It seems you used the web interface to create this patch, which is... not the most amenable to following up on review comments, though if you want to continue working from there, that's fine by me (though you probably will have trouble if you wind up needing to rebase anything...). Let me know if you help with anything like using git on a local or running the tidy check or whatnot.

[root-goblin]

It seems you used the web interface to create this patch, which is... not the most amenable to following up on review comments, though if you want to continue working from there, that's fine by me (though you probably will have trouble if you wind up needing to rebase anything...).

I realised this too late as I do probably need to do some sort of a squash, I somehow imagined the web interface to be more capable than it actually is.

I could reopen a new PR that is better formatted if a cleaner commit is preferred.

[workingjubilee]

Ah, no need to open a new PR.

I think the GitHub Codespaces interface is slightly more capable, although I've never used it for this repo so don't trust anything I say there.

In practice when I've used the web interface to create a patch and then am asked to iterate on it, what I usually have done is "just" clone the repo, add my fork as a remote, and then checkout the branch GitHub automatically created for me, and then I can just pull/push or whatever as I like.

If you wind up having difficulty doing that I'm happy to do it for you once we're done with review, as long as you're okay with me making decisions about how to reorganize the info in your commits~

[root-goblin]

Okay I think it's ready for a review, I now understand tidy is catching the whitespace my editor was sneaking in.

Okay with me making decisions about how to reorganize the info in your commits~

For sure.

[root-goblin]

@rustbot review

[workingjubilee]

Found some typos and interesting word choices.

[root-goblin]

@rustbot review

[workingjubilee]

Cool, this looks good! Want to rebase this before I send it in?

[rustbot]

There are merge commits (commits with multiple parents) in your changes. We have a no merge policy so these commits will need to be removed for this pull request to be merged.

You can start a rebase with the following commands:

$ # rebase
$ git pull --rebase https://github.com/rust-lang/rust.git master
$ git push --force-with-lease

The following commits are merge commits:

• 8bfae59

[workingjubilee]

Hm!

[root-goblin]

I have pressed quite a spicy button, I think it's probably best to kill this one and reopen against master with just the changes.

Edit: I can reopen if there's some way of salvaging, but my side's history is going to be somewhat tricky to untangle - I'm not going to put that mess onto anyone else to figure out.

[workingjubilee]

@root-goblin This is the sequence of commands I used to take the merge commit, undo it, reset the repository state, and then rebase and push to your branch. It has been edited somewhat to remove a few back-and-forth steps, as those would have been misleading.

git remote add rootgoblin git@github.com:root-goblin/rust.git
git fetch rootgoblin patch-1
git checkout rootgoblin/patch-1
git reset HEAD~1
git reset --hard
git status
rm -fr tests/ui
git reset --hard
git status
rm -fr compiler
rm -fr src
rm -fr tests
git reset --hard
git status
rm -fr library/std/src/os/rtems
rm -fr library/std/src/sys
git reset --hard
git log
git rebase -i HEAD~5
git status
git show
git switch -c patch-1
git push --set-upstream rootgoblin patch-1 --force

[workingjubilee]

It actually only took me a couple minutes, I just didn't notice you asked for help until now because it was closed. 😅

[root-goblin]

@root-goblin This is the sequence of commands ...

Thanks for sorting it out! I'm definitely not familiar enough with this repo's commit conventions to boldly reset --hard

[workingjubilee]

git reset --hard per se can only bring the repository's actual files visible to you closer to the state described by the current commit. So assuming you don't want to preserve any current additional work, it is safe. And the original git reset HEAD~1 was just popping off the merge commit.

[workingjubilee]

...also, while I left in a couple of instances of git status and git show, there were about five times as many in the actual history, partly because I am the sort of person that runs ls, thinks about what just was printed to the screen, and then runs ls again, to see if anything changed in the 0 commands between. 😅

[workingjubilee]

Nice.

[workingjubilee]

@bors r+ rollup

[bors]

📌 Commit 4198594 has been approved by workingjubilee

It is now in the queue for this repository.

[root-goblin]

git reset --hard per se can only bring the repository's actual files visible to you closer to the state described by the current commit. So assuming you don't want to preserve any current additional work, it is safe. And the original git reset HEAD~1 was just popping off the merge commit.

I have not thought of it that way before, but yeah that makes sense.

Thanks for helping out with the PR!