This updates the book repository, but mostly to include
https://github.com/rust-lang/book/pull/1180
TL;DR: the second edition is close enough to done that we should
universally recommend it over the first edition.
Update .mailmap with my real name
Good morning, the Rust team!
Once upon a time I was a modest-scale contributor. Sadly, various turbulences made me step away from my participation in the project. It's great to see how far it's gone.
I would appreciate it if you accepted this small change to the .mailmap file so that it shows my real name as back then I was using an alias. If doubts arise if I am the same person, I will be happy to provide further evidence. :)
Kind regards.
rustdoc: move manual "extern crate" statements outside automatic "fn main"s in doctests
Gated on https://github.com/rust-lang/rust/pull/48095 - I based the branch atop that so i could show off the change in one of its tests, the actual change in this PR is just the last commit
There are a handful of unfortunate assumptions in the way rustdoc processes `extern crate` statements in doctests:
1. In the absence of an `extern crate` statement in the test, if the test also uses the local crate name, it will automatically insert an `extern crate cratename;` statement into the test.
2. If the doctest *does* include an `extern crate` statement, rustdoc will not automatically insert one, on the assumption that doing so would introduce a duplicate import.
3. If a doctest does not have the substring `fn main` outside a comment, rustdoc will wrap the whole doctest in a generated `fn main` so it can be compiled.
In short, whenever you write a doctest like this...
```rust
//! extern crate my_crate;
//! my_crate::some_cool_thing();
```
...rustdoc will turn it into (something like) this:
```rust
fn main() {
extern crate my_crate;
my_crate::some_cool_thing();
}
```
This creates issues when compiled, because now `my_crate` isn't even properly in scope! This forces people who want to have multiple crates in their doctests (or an explicit `extern crate` statement) to also manually include their own `fn main`, so rustdoc doesn't put their imports in the wrong place.
This PR just taps into another processing step rustdoc does to doctests: Whenever you add an `#![inner_attribute]` to the beginning of a doctest, rustdoc will actually splice those out and put it before the generated `fn main`. Now, we can just do the same with `extern crate`s at the beginning, too, and get a much nicer experience.
Now, the above example will be converted into this:
```rust
extern crate my_crate;
fn main() {
my_crate::some_cool_thing();
}
```
Generate documentation for auto-trait impls
A new section is added to both both struct and trait doc pages.
On struct/enum pages, a new 'Auto Trait Implementations' section displays any synthetic implementations for auto traits. Currently, this is only done for Send and Sync.
On trait pages, a new 'Auto Implementors' section displays all types which automatically implement the trait. Effectively, this is a list of all public types in the standard library.
Synthesized impls for a particular auto trait ('synthetic impls') take generic bounds into account. For example, a type
```rust
struct Foo<T>(T)
```
will have 'impl<T> Send for Foo<T> where T: Send' generated for it.
Manual implementations of auto traits are also taken into account. If we have
the following types:
```rust
struct Foo<T>(T)
struct Wrapper<T>(Foo<T>)
unsafe impl<T> Send for Wrapper<T>' // pretend that Wrapper<T> makes this sound somehow
```
Then Wrapper will have the following impl generated:
```rust
impl<T> Send for Wrapper<T>
```
reflecting the fact that 'T: Send' need not hold for 'Wrapper<T>: Send' to hold
Lifetimes, HRTBS, and projections (e.g. '<T as Iterator>::Item') are taken into account by synthetic impls:
However, if a type can *never* implement a particular auto trait (e.g. `struct MyStruct<T>(*const T)`), then a negative impl will be generated (in this case, `impl<T> !Send for MyStruct<T>`)
All of this means that a user should be able to copy-paste a syntheticimpl into their code, without any observable changes in behavior (assuming the rest of the program remains unchanged).
Current document takes 2^4, which is equal to 4^2.
This example is not very helpful for those unfamiliar with math words in English and thus rely on example codes.
