Skip to content

std::iter: document iteration over &T and &mut T#79360

Merged
bors merged 2 commits intorust-lang:masterfrom
wchargin:wchargin-doc-iter-by-reference
Dec 13, 2020
Merged

std::iter: document iteration over &T and &mut T#79360
bors merged 2 commits intorust-lang:masterfrom
wchargin:wchargin-doc-iter-by-reference

Conversation

@wchargin
Copy link
Contributor

@wchargin wchargin commented Nov 23, 2020 •
edited
Loading

A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what &mut does in iterating over &mut foo:

for value in &mut self.my_vec {
    // ...
}

My colleague had read the std::iter docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions iter_mut, but it doesn’t cover the purpose
of &mut coll for a collection coll. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that impl<I: Iterator> IntoIterator for I, and
it’s nice for the existing “three forms of iteration” to appear near the
top.

Test Plan:
Ran ./x.py doc library/core, and the result looked good, including
links. Manually copy-pasted the two doctests into the playground and ran
them.

wchargin-branch: doc-iter-by-reference

@wchargin
std::iter: document iteration over &T and &mut T
ce3d604 
A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what `&mut` does in iterating over `&mut foo`:

```rust
for value in &mut self.my_vec {
    // ...
}
```

My colleague had read the `std::iter` docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions `iter_mut`, but it doesn’t cover the purpose
of `&mut coll` for a collection `coll`. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that `impl<I: Iterator> IntoIterator for I`, and
it’s nice for the existing “three forms of iteration” to appear near the
top.

Implementation note: I haven’t linkified the references to `HashSet` and
`HashMap`, since those are in `std` and these docs are in `core`;
linkifying them gave an “unresolved link” rustdoc error.

Test Plan:
Ran `./x.py doc library/core`, and the result looked good. Manually
copy-pasted the two doctests into the playground and ran them.

wchargin-branch: doc-iter-by-reference
wchargin-source: 0f35369a8a735868621166608797744e97536792
@rust-highfive
Copy link
Contributor

rust-highfive commented Nov 23, 2020

r? @withoutboats

(rust_highfive has picked a reviewer for you, use r? to override)

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 23, 2020
@wchargin
Copy link
Contributor Author

wchargin commented Nov 23, 2020

@rustbot modify labels +T-doc

@rustbot rustbot added the A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools label Nov 23, 2020
@camelid camelid added A-iterators Area: Iterators T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Nov 23, 2020
@camelid
Copy link
Member

camelid commented Nov 23, 2020

This seems good!

jyn514
jyn514 reviewed Nov 23, 2020
View reviewed changes
@wchargin
[update patch]
6edc90a 
wchargin-branch: doc-iter-by-reference
wchargin-source: e4069ac9a9d73860467cea74cf3ae1605af37d74
@crlf0710 crlf0710 added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 11, 2020
@Dylan-DPC-zz
Copy link

Dylan-DPC-zz commented Dec 11, 2020

r? @KodrAus

@m-ou-se
Copy link
Member

m-ou-se commented Dec 11, 2020

This is great, thanks!

@bors r+ rollup

@bors
Copy link
Collaborator

bors commented Dec 11, 2020

📌 Commit 6edc90a has been approved by m-ou-se

@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 Dec 11, 2020
@m-ou-se m-ou-se assigned m-ou-se and unassigned KodrAus Dec 11, 2020
@camelid
Copy link
Member

camelid commented Dec 11, 2020

Test Plan:
Ran ./x.py doc library/core, and the result looked good, including
links. Manually copy-pasted the two doctests into the playground and ran
them.

@wchargin Btw, I don't think you should worry about testing manually! CI should run the equivalent for you.

Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request Dec 12, 2020
@Dylan-DPC
Rollup merge of rust-lang#79360 - wchargin:wchargin-doc-iter-by-refer…
00d215b 
…ence, r=m-ou-se

std::iter: document iteration over `&T` and `&mut T`

A colleague of mine is new to Rust, and mentioned that it was “slightly
confusing” to figure out what `&mut` does in iterating over `&mut foo`:

```rust
for value in &mut self.my_vec {
    // ...
}
```

My colleague had read the `std::iter` docs and not found the answer
there. There is a brief section at the top about “the three forms of
iteration”, which mentions `iter_mut`, but it doesn’t cover the purpose
of `&mut coll` for a collection `coll`. This patch adds an explanatory
section to the docs. I opted to create a new section so that it can
appear after the note that `impl<I: Iterator> IntoIterator for I`, and
it’s nice for the existing “three forms of iteration” to appear near the
top.

Test Plan:
Ran `./x.py doc library/core`, and the result looked good, including
links. Manually copy-pasted the two doctests into the playground and ran
them.

wchargin-branch: doc-iter-by-reference
@Dylan-DPC-zz Dylan-DPC-zz mentioned this pull request Dec 12, 2020
Closed
@JohnTitor JohnTitor mentioned this pull request Dec 13, 2020
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Dec 13, 2020
@bors
Auto merge of rust-lang#79994 - JohnTitor:rollup-43wl2uj, r=JohnTitor
1281315 
Rollup of 12 pull requests

Successful merges:

 - rust-lang#79360 (std::iter: document iteration over `&T` and `&mut T`)
 - rust-lang#79398 (Link loop/for keyword)
 - rust-lang#79834 (Remove deprecated linked_list_extras methods.)
 - rust-lang#79845 (Fix rustup support in default_build_triple for python3)
 - rust-lang#79940 (fix more clippy::complexity findings)
 - rust-lang#79942 (Add post-init hook for static memory for miri.)
 - rust-lang#79954 (Fix building compiler docs with stage 0)
 - rust-lang#79963 (Fix typo in `DebruijnIndex` documentation)
 - rust-lang#79970 (Misc rustbuild improvements when the LLVM backend isn't used)
 - rust-lang#79973 (rustdoc light theme: Fix CSS for selected buttons)
 - rust-lang#79984 (Remove an unused dependency that made `rustdoc` crash)
 - rust-lang#79985 (Fixes submit event of the search input)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit 1698773 into rust-lang:master Dec 13, 2020
@rustbot rustbot added this to the 1.50.0 milestone Dec 13, 2020
@wchargin wchargin deleted the wchargin-doc-iter-by-reference branch December 13, 2020 06:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@jyn514 jyn514 jyn514 left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@m-ou-se m-ou-se

Labels

A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-iterators Area: Iterators S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-libs-api Relevant to the library API team, which will review and decide on the PR/issue.

Projects

None yet

Milestone

1.50.0

Development

Successfully merging this pull request may close these issues.