Due to the way iterators work, the std::iter module is chock full of
structs that you, humble Rust programmer, will never actually use.
However, they have URLs, and therefore get linked to, because they are
real structs that do exist.
So, rather than just have a tiny sentence about each one of them,
this patch adds links back to the functions and methods on Iterator
which actually create the structs, where helpful documentation already
exists.
This change has two consequences:
1. It makes `Arc<T>` and `Rc<T>` covariant in `T`.
2. It causes the compiler to reject code that was unsound with respect
to dropck. See compile-fail/issue-29106.rs for an example of code that
no longer compiles. Because of this, this is a [breaking-change].
Fixes#29037.
Fixes#29106.
Due to the way iterators work, the std::iter module is chock full of
structs that you, humble Rust programmer, will never actually use.
However, they have URLs, and therefore get linked to, because they are
real structs that do exist.
So, rather than just have a tiny sentence about each one of them,
this patch adds links back to the functions and methods on Iterator
which actually create the structs, where helpful documentation already
exists.
I found these automatically, but fixed them manually to ensure the semantics are correct. I know things like these are hardly important, since they only marginally improve clarity. But at least for me typos and simple grammatical errors trigger an---unjustified---sense of unprofessionalism, despite the fact that I make them all the time and I understand that they're the sort of thing that is bound to slip through review.
Anyway, to find most of these I used:
* `ag '.*//.*(\b[A-Za-z]{2,}\b) \1\b'` for repeated words
* `ag '\b(the|this|those|these|a|it) (a|the|this|those|these|it)\b'` to find constructs like 'the this' etc. many false positives, but not too hard to scroll through them to actually find the mistakes.
* `cat ../../typos.txt | paste -d'|' - - - - - - - - - - - - - - - - - - - - - - | tr '\n' '\0' | xargs -0 -P4 -n1 ag`. Hacky way to find misspellings, but it works ok. I got `typos.txt` from [Wikipedia](https://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_machines)
* `ag '.*//.* a ([ae][a-z]|(o[^n])|(i[a-rt-z]))'` to find places where 'a' was followed by a vowel (requiring 'an' instead).
I also used a handful more one off regexes that are too boring to reproduce here.
Our docs were very basic for the various versions of from_utf8, so
this commit beefs them up.
It also improves docs for the &str variant's error, Utf8Error.
Our docs were very basic for the various versions of from_utf8, so
this commit beefs them up.
It also improves docs for the &str variant's error, Utf8Error.
Steve Klabnik
